Account Addresses

Account_Addresses - Create account address

Create a new account address

https://example.sonar.software/api/v1/accounts/:account_id/addresses

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

line1 String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

The county, for US addresses

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Addresses - Delete account address

Delete an account address

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field Type Description
account_id Number

The ID of the account

address_id Number

The ID of the address

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the address could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Addresses - Get all account addresses

Get a list of the addresses for account ID :account_id

https://example.sonar.software/api/v1/accounts/:account_id/addresses

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

A valid county for the subdivision obtained from /_data/counties, null if not a US address

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Addresses - Get individual account address

Get an individual account address.

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field Type Description
account_id Number

The ID of the account

address_id Number

The ID of the address

county String

A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Account_Addresses - Update account address

Update an account address.

https://example.sonar.software/api/v1/accounts/:account_id/addresses/:address_id

Parameter

Field Type Description
account_id Number

The ID of the account to update the address on

address_id Number

The ID of the address

line1 optional String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city optional String

The city

state optional String

The state, province or other country subdivision

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

The ZIP/postal code

country optional String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude optional Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude optional Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id optional Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Account Billing

Account_Billing - Get account billing details

Get some details about the accounts billing details. This is mainly used for the customer portal.

https://example.sonar.software/api/v1/accounts/:id/billing_details

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
balance_due Number

The balance due on the account, including any child accounts

next_recurring_charge_amount Number

The estimated amount of the next monthly recurring bill, including taxes

total_balance Number

The balance due, plus any un-invoiced charges on the account

available_funds Number

Any unapplied deposits (payments) or discounts on the account

next_bill_date Date

The next date a monthly bill will be generated, can be null

 HTTP/1.1 200 OK
 {
  "data": {
    "balance_due": 586.5,
    "balance_total": 789.5,
    "next_recurring_charge_amount": 0,
    "next_bill_date": null,
    "available_funds": 123.45
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days before the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

switch_status_after_delinquency Boolean

Whether or not this account should be switched into a new inactive status after X days of delinquency.

days_of_delinquency_for_status_switch Integer

If switch_status_after_delinquency is true, this is the number of days of delinquency to allow before switching status

delinquency_account_status_id Integer

The account status ID to switch into after days_of_delinquency_for_status_switch is exceeded. Must be an inactive status.

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing",
    "switch_status_after_delinquency": false,
    "days_of_delinquency_for_status_switch": 100,
    "delinquency_account_status_id": 3
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days before the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice"
  }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": false,
         "separate_invoice_day_enabled": true,
         "invoice_day": 1
    }
}

Account_Billing - Get account billing parameters

Get the account billing parameters

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": false
    }
}

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day Number

The day of the month that the account bills

due_days Number

The number of days before the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

prorate Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

switch_status_after_delinquency Boolean

Whether or not this account should be switched into a new inactive status after X days of delinquency.

days_of_delinquency_for_status_switch Integer

If switch_status_after_delinquency is true, this is the number of days of delinquency to allow before switching status

delinquency_account_status_id Integer

The account status ID to switch into after days_of_delinquency_for_status_switch is exceeded. Must be an inactive status.

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days before the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

switch_status_after_delinquency Boolean

Whether or not this account should be switched into a new inactive status after X days of delinquency.

days_of_delinquency_for_status_switch Integer

If switch_status_after_delinquency is true, this is the number of days of delinquency to allow before switching status

delinquency_account_status_id Integer

The account status ID to switch into after days_of_delinquency_for_status_switch is exceeded. Must be an inactive status.

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing",
    "switch_status_after_delinquency": false,
    "days_of_delinquency_for_status_switch": 100,
    "delinquency_account_status_id": 3
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day optional Number

The day of the month that the account bills

due_days optional Number

The number of days before the invoice becomes past due

grace_days optional Number

The number of days after the invoice is past due that penalties are applied

grace_until optional Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill optional Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt optional Boolean

Whether or not the account is tax exempt

prorate optional Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice optional Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled optional Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day optional Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days optional Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode optional String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day optional String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day optional String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days before the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

due_days_day String

Whether the due_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice",
    "due_days_day": "billing"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day optional Number

The day of the month that the account bills

due_days optional Number

The number of days after billing that the invoice becomes past due

grace_days optional Number

The number of days after the invoice is past due that penalties are applied

grace_until optional Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill optional Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt optional Boolean

Whether or not the account is tax exempt

prorate optional Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice optional Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled optional Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day optional Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days optional Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode optional String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day optional String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

auto_pay_day String

Whether the auto_pay_days value is counted from the billing date or the invoice date. Only applies if separate_invoice_day_enabled is true.

Allowed values: "billing", "invoice"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice",
    "auto_pay_day": "invoice"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day optional Number

The day of the month that the account bills

due_days optional Number

The number of days after billing that the invoice becomes past due

grace_days optional Number

The number of days after the invoice is past due that penalties are applied

grace_until optional Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill optional Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt optional Boolean

Whether or not the account is tax exempt

prorate optional Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice optional Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled optional Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day optional Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days optional Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode optional String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

auto_pay_days Number

The number of days after automatic invoice generation that any auto-pay methods are charged

bill_mode String

Whether the user receives an invoice or a statement

Allowed values: "invoice", "statement"

HTTP/1.1 200 OK
{
  "data": {
    "bill_day": 18,
    "due_days": 10,
    "grace_days": 3,
    "grace_until": null,
    "months_to_bill": 1,
    "tax_exempt": false,
    "print_invoice": false,
    "separate_invoice_day_enabled": false,
    "invoice_day": 1,
    "auto_pay_days": 3,
    "bill_mode": "invoice"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day optional Number

The day of the month that the account bills

due_days optional Number

The number of days after billing that the invoice becomes past due

grace_days optional Number

The number of days after the invoice is past due that penalties are applied

grace_until optional Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill optional Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt optional Boolean

Whether or not the account is tax exempt

prorate optional Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice optional Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled optional Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day optional Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

separate_invoice_day_enabled Boolean

Whether or not invoices generated during automatic billing have a different invoice date/billing period than the day billing runs

invoice_day Number

If separate_invoice_day_enabled is true, this is the day of the following month that any automatic invoices will show as their date/billing period.

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account_Billing - Update account billing parameters

Update an accounts billing parameters. This requires account super user permission

https://example.sonar.software/api/v1/accounts/:id/billing_parameters

Parameter

Field Type Description
id Number

The ID of the account to update

bill_day optional Number

The day of the month that the account bills

due_days optional Number

The number of days after billing that the invoice becomes past due

grace_days optional Number

The number of days after the invoice is past due that penalties are applied

grace_until optional Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill optional Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt optional Boolean

Whether or not the account is tax exempt

prorate optional Boolean

Whether or not to prorate the change, if you are updating the bill_day. If this is omitted, the system prorate default will be used. If this is included, it will override the default

print_invoice optional Boolean

Whether or not the account receives a printed invoice

Success 200

Field Type Description
bill_day Number

The day of the month that the account bills

due_days Number

The number of days after billing that the invoice becomes past due

grace_days Number

The number of days after the invoice is past due that penalties are applied

grace_until Date

A date that the account is graced until. This overrides grace_days until the date is passed, and then the account reverts to the grace_days parameter. This is null if unset

months_to_bill Number

The number of months that are invoiced at a time. For example, if this is 6, an invoice will be generated once every 6 months for 6 months worth of charges

tax_exempt Boolean

Whether or not the account is tax exempt

print_invoice Boolean

Whether or not the account receives a printed invoice

HTTP/1.1 200 OK
{
    "data": {
         "bill_day": 11,
         "due_days": 10,
         "grace_days": 3,
         "grace_until": null,
         "months_to_bill": 1,
         "tax_exempt": false,
         "print_invoice": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "grace_until": "The grace until does not match the format Y-m-d."
         },
         "status_code": 422
     }
 }

Account Call Logs

Account_Call_Logs - Create a new call log

Create a new call log.

https://example.sonar.software/api/v1/accounts/:id/call_logs

Parameter

Field Type Description
id Number

The ID of the account

time_in_seconds Number

How long the call lasted, in seconds

subject String

The subject of the call

body String

A longer description of the call

Success 200

Field Type Description
id Number

The ID of the call log.

account_id Number

The ID of the account

time_in_seconds Number

How long the call lasted, in seconds

subject String

The subject of the call

body String

A longer description of the call

user_id Number

The ID of the user who created the call log

created_at DateTime

The date and time the call log was created in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Blah blah blah blah blah",
    "user_id": 1,
    "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "time_in_seconds": "The time_in_seconds must be an integer."
     },
     "status_code": 422
   }
 }

Account_Call_Logs - Delete a call log

Delete a call log. Requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field Type Description
id Number

The account ID

call_log_id Number

The call log ID

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the call log could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Call log does not exist.",
         "status_code": 404
     }
 }

Account_Call_Logs - Get all call logs

Get all call logs

https://example.sonar.software/api/v1/accounts/:id/call_logs

Parameter

Field Type Description
id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the call log.

account_id Number

The ID of the account

time_in_seconds Number

How long the call lasted, in seconds

subject String

The subject of the call

body String

A longer description of the call

user_id Number

The ID of the user who created the call log

created_at DateTime

The date and time the call log was created in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "account_id": 2,
      "time_in_seconds": 12,
      "subject": "Support issue",
      "body": "Blah blah blah blah blah",
      "user_id": 1,
      "created_at": "2016-05-20 14:14:33"
    },
    {
      "id": 2,
      "account_id": 2,
      "time_in_seconds": 12,
      "subject": "Support issue",
      "body": "Blah blah blah blah blah again!",
      "user_id": 1,
      "created_at": "2016-05-20 14:14:33"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Call_Logs - Get an individual call log

Get an individual call log

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field Type Description
id Number

The ID of the account

call_log_id Number

The ID of the call log

Success 200

Field Type Description
id Number

The ID of the call log.

account_id Number

The ID of the account

time_in_seconds Number

How long the call lasted, in seconds

subject String

The subject of the call

body String

A longer description of the call

user_id Number

The ID of the user who created the call log

created_at DateTime

The date and time the call log was created in UTC

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Blah blah blah blah blah",
    "user_id": 1,
    "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Call_Logs - Update call log

Update an existing call log. Requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/call_logs/:call_log_id

Parameter

Field Type Description
id Number

The account ID

call_log_id Number

The call log ID

time_in_seconds optional Number

How long the call lasted, in seconds

subject optional String

The subject of the call

body optional String

The body of the call

Success 200

Field Type Description
id Number

The ID of the call log.

account_id Number

The ID of the account

time_in_seconds Number

How long the call lasted, in seconds

subject String

The subject of the call

body String

A longer description of the call

user_id Number

The ID of the user who created the call log

created_at DateTime

The date and time the call log was created in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "account_id": 2,
    "time_in_seconds": 12,
    "subject": "Support issue",
    "body": "Please don't write 'blah blah blah blah blah' in call logs.",
    "user_id": 1,
   "created_at": "2016-05-20 14:14:33"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Call Records

Account_Call_Records - Get account call records

Get a list of call records on the account, between :start_date and :end_date, in YYYY-MM-DD format. The dates are checked in UTC (as call records are stored/entered with UTC.) For example, if you want to see all calls on 2016-08-01 UTC, you should enter 2016-08-01 as the start and 2016-08-02 as the end.

https://example.sonar.software/api/v1/accounts/:account_id/call_records/:start_date/:end_date

Parameter

Field Type Description
account_id Number

The ID of the account

start_date Date

The start date, in UTC. YYYY-MM-DD format.

end_date Date

The end date, in UTC. YYYY-MM-DD format.

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the call record

origination String

The originating DID

destination String

The destination DID

call_start DateTime

The call start, in UTC

duration_in_seconds Integer

The length of the call, in seconds

matched_prefix String

The prefix that was matched for billing

prefix_name String

A descriptive name for the prefix match

rate Number

The rate, to 20 decimal places

local Boolean

Whether or not the call was rated as local

long_distance Boolean

Whether or not the call was rated as long distance

service_id Integer

The service ID this call was rated against

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 8,
      "origination": "14145132472",
      "destination": "18007776666",
      "call_start": "2016-08-26 16:09:46",
      "duration_in_seconds": 1999,
      "matched_prefix": "1800",
      "prefix_name": "TOLL FREE",
      "rate": "0.00000000000000000000",
      "local": false,
      "long_distance": false,
      "service_id": 5
    },
    {
      "id": 7,
      "origination": "14145132472",
      "destination": "011376312341231234",
      "call_start": "2016-08-26 16:09:46",
      "duration_in_seconds": 154,
      "matched_prefix": "3763",
      "prefix_name": "ANDORRA",
      "rate": "0.36400000000000000000",
      "local": false,
      "long_distance": false,
      "service_id": 5
    }
  ],
  "paginator": {
    "total_count": 8,
    "total_pages": 4,
    "current_page": 1,
    "limit": 2
  }
}

Account Contacts

Account_Contacts - Create account contact

Create a new account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field Type Description
account_id Number

The ID of the account

name String

The name of the contact

role optional String

The role of the contact

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

username optional String

A username for the customer portal. Required if password is set.

password optional String

A password for the customer portal. Required if username is set.

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

username String

A username for the customer portal

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": true,
       "username": "babymonkey"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name field is required.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Create account contact

Create a new account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field Type Description
account_id Number

The ID of the account

name String

The name of the contact

role optional String

The role of the contact

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The number field must be a number.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Delete account contact

Delete an account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field Type Description
account_id Number

The ID of the account

contact_id Number

The ID of the contact

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Contact deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the contact could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "That contact ID does not exist.",
         "status_code": 404
     }
 }

Account_Contacts - Get all account contacts

Get the contacts for an account

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

username String

The username this contact has setup for the customer portal

{
    "data": [
        {
            "id": 1,
            "name": "Simon Westlake",
            "role": "CEO",
            "email_address": "simon@sonar.software",
            "phone_numbers": {
                "work": {
                    "number": "1231231234",
                    "extension": 123
                },
                "mobile": {
                    "number": "4148675309",
                    "extension": null
                }
            },
            "email_message_categories": [
                2
            ],
            "primary": true,
            "username": "leethacker12345"
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Contacts - Get all account contacts

Get the contacts for an account

https://example.sonar.software/api/v1/accounts/:account_id/contacts

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

{
    "data": [
        {
            "id": 1,
            "name": "Simon Westlake",
            "role": "CEO",
            "email_address": "simon@sonar.software",
            "phone_numbers": {
                "work": {
                    "number": "1231231234",
                    "extension": 123
                },
                "mobile": {
                    "number": "4148675309",
                    "extension": null
                }
            },
            "email_message_categories": [
                2
            ],
            "primary": true
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_Contacts - Get individual account contact

Get an individual account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field Type Description
account_id Number

The ID of the account

contact_id Number

The ID of the contact

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

username String

The username this contact has setup for the customer portal

HTTP/1.1 200 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
        "email_message_categories": [
           2
        ],
       "primary": true,
       "username": null
    }
}

Account_Contacts - Get individual account contact

Get an individual account contact

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field Type Description
account_id Number

The ID of the account

contact_id Number

The ID of the contact

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact

HTTP/1.1 200 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
        "email_message_categories": [
           2
        ],
       "primary": true
    }
}

Account_Contacts - Update account contact

Update an account contact.

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field Type Description
account_id Number

The ID of the account

contact_id Number

The ID of the contact

name optional String

The name of the contact

role optional String

The role of the contact

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories optional Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary optional Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

username optional String

A username for the customer portal.

password optional String

A password for the customer portal. Required if username is currently null, as you are creating a new account.

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

username String

The username for the customer portal

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ],
       "primary": false,
       "username": "ridingonapig"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name field is required.",
         },
         "status_code": 422
     }
 }

Account_Contacts - Update account contact

Update an account contact.

https://example.sonar.software/api/v1/accounts/:account_id/contacts/:contact_id

Parameter

Field Type Description
account_id Number

The ID of the account

contact_id Number

The ID of the contact

name optional String

The name of the contact

role optional String

The role of the contact

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

Success 200

Field Type Description
id Number

The ID of the contact

name String

The name of the contact

role String

The role of the contact

email_address String

The email address of the contact

phone_numbers Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension.

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

primary Boolean

Whether or not this the primary contact. Only one contact can be primary, setting a contact to primary will remove the attribute from all other contacts

HTTP/1.1 201 OK
{
    "data": {
        "id": 46,
        "name": "Jacob Kailing",
        "role": "Chief Party Officer",
        "email_address": "jacob@sonar.software",
        "phone_numbers": {
           "work": {
               "number": "1231231234",
               "extension": 123
           },
           "mobile": {
               "number": "1235550809",
               "extension": null
           }
       },
       "email_message_categories": [
           2
       ]
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The number field must be a number.",
         },
         "status_code": 422
     }
 }

Account DIDs

Account_DIDs - Assign a DID to an account

Assign a currently unassigned DID to an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids

Parameter

Field Type Description
account_id Integer

The ID of the account

did String

The DID to assign. This DID must already have been inventoried in Sonar.

service_id Integer

The ID of a voice service to associate the DID with. This voice service must already be on the account.

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

service_id Integer

The ID of the voice service.

rate_center_id Integer

The ID of the rate center that the DID is in

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 30,
    "rate_center_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
  "error": {
    "message": "DID is already assigned to account 1.",
    "status_code": 422
  }
}

Account_DIDs - Get all DIDs assigned to account

Get all DIDs assigned to the account.

https://example.sonar.software/api/v1/accounts/:account_id/dids

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

service_id Integer

The ID of the voice service.

rate_center_id Integer

The ID of the rate center that the DID is in

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 7,
      "did": "1234567892",
      "account_id": 1,
      "service_id": 30,
      "rate_center_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_DIDs - Get an individual DID assigned to an account

Get an individual DID associated with an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field Type Description
account_id Integer

The ID of the account

did_id Integer

The ID of the DID

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

service_id Integer

The ID of the voice service.

rate_center_id Integer

The ID of the rate center that the DID is in

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 30,
    "rate_center_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_DIDs - Move a DID to another voice service

Update an existing DID assignment to change the assigned service

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field Type Description
account_id Integer

The ID of the account

did_id Integer

The ID of the DID

service_id Integer

The ID of a voice service on the account

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

service_id Integer

The ID of the voice service.

rate_center_id Integer

The ID of the rate center that the DID is in

HTTP/1.1 201 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": 1,
    "service_id": 31,
    "rate_center_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_DIDs - Unassign a DID from an account

Unassociate a DID from an account.

https://example.sonar.software/api/v1/accounts/:account_id/dids/:did_id

Parameter

Field Type Description
account_id Integer

The ID of the account

did_id Integer

The ID of the DID

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

service_id Integer

The ID of the voice service.

rate_center_id Integer

The ID of the rate center that the DID is in

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "did": "1234567892",
    "account_id": null,
    "service_id": null,
    "rate_center_id": 1
  }
}

Error 4xx

Name Type Description
message String

A reason as to why the rate center could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Data Usage

Account_Data_Usage - Add additional capacity to an account

Add additional capacity for an account. This is a temporary top off for the current billing period. The account must have a data service with a usage based billing policy associated with it. The policy must be configured to allow additional capacity to be added.

https://example.sonar.software/api/v1/accounts/:id/top_off

Parameter

Field Type Description
id Number

The ID of the account

quantity Number

The number of 'top offs' to apply. For example, if the overage service on the usage based billing policy defines 5 gigabytes as one unit, setting this to 2 would add 10 gigabytes.

Default value: 1

Success 200

Field Type Description
bytes_added String

The number of bytes added

HTTP/1.1 200 OK
{
  "data": {
    "bytes_added": 5000000000
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "The account does not have a data service with a usage based billing policy.",
     "status_code": 422
   }
 }

Account_Data_Usage - Add bulk granular data usage to many accounts

Add granular data usage to many accounts. This will contribute to the accounts overall data usage, and will be added to billable/free usage. The max size of this batch is 5000, please split into smaller chunks if you have more data.

https://example.sonar.software/api/v1/accounts/bulk_granular_data_usage

{
    "data": [
        {
            "timestamp": 1451606400,
            "in": 1,
            "out": 3,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown",
            "account_id": 12
        },
        {
            "timestamp": 1451606460,
            "in": 141,
            "out": 1807,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown",
            "account_id": 4938
        }
    ]
 }

Parameter

Field Type Description
id Number

The ID of the account

data Array

An array of data to be stored, the format of which is described below this entry.

timestamp Number

A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.

in Number

An integer representing the number of bytes of inbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.

out Number

An integer representing the number of bytes of outbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.

data_source_identifier String

A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.

data_source_parent String

A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.

data_type String

The type of data (e.g. HTTP, SSH, ICMP) - you can submit something generic like 'Unknown' if you don't track the type of data being used.

account_id Integer

The ID of the account this data should be added to

Success 200

Field Type Description
success String

This will return true on success. If you want to get the data, use the GET endpoint.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "data.0.in": "The data.0.in must be a number."
     },
     "status_code": 422
   }
 }

Account_Data_Usage - Add granular data usage to an account

Add granular data usage to an account. This will contribute to the accounts overall data usage, and will be added to billable/free usage. The max size of this batch is 5000, please split into smaller chunks if you have more data.

https://example.sonar.software/api/v1/accounts/:id/granular_data_usage

{
    "data": [
        {
            "timestamp": 1451606400,
            "in": 1,
            "out": 3,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown"
        },
        {
            "timestamp": 1451606460,
            "in": 141,
            "out": 1807,
            "data_source_identifier": "192.168.100.123",
            "data_source_parent": "Router-01-Example.sonar.software",
            "data_type": "Unknown"
        }
    ]
 }

Parameter

Field Type Description
id Number

The ID of the account

data Array

An array of data to be stored, the format of which is described below this entry.

timestamp Number

A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.

in Number

An integer representing the number of bytes of inbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.

out Number

An integer representing the number of bytes of outbound traffic to store for this timestamp. This should be a counter (e.g. it should increase above the previous value) and not a gauge (the difference from the last value to this one.) If this value is less than the prior value, it will be treated as a counter wrap and discarded.

data_source_identifier String

A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.

data_source_parent String

A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.

data_type String

The type of data (e.g. HTTP, SSH, ICMP) - you can submit something generic like 'Unknown' if you don't track the type of data being used.

Success 200

Field Type Description
success String

This will return true on success. If you want to get the data, use the GET endpoint.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "data.0.in": "The data.0.in must be a number."
     },
     "status_code": 422
   }
 }

Account_Data_Usage - Get all aggregated data usage for an account

Get the aggregated data usage for an account, split into billing periods.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories

Parameter

Field Type Description
id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the data usage history

billable_in_bytes Number

The number of billable inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

billable_out_bytes Number

The number of billable outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

free_in_bytes Number

The number of free inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

free_out_bytes Number

The number of free outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

start_time DateTime

When the data began to be aggregated (UTC)

closed_time DateTime

When the data aggregation was stopped for this item (UTC.) If null, this data is still open and is for the current billing period.

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 136,
      "billable_in_bytes": 0,
      "billable_out_bytes": 0,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-06-25 00:51:18",
      "closed_time": null
    },
    {
      "id": 128,
      "billable_in_bytes": 6000000000,
      "billable_out_bytes": 6000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-05-25 00:49:48",
      "closed_time": "2016-06-25 00:51:18"
    },
    {
      "id": 127,
      "billable_in_bytes": 5000000000,
      "billable_out_bytes": 5000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-04-25 00:49:48",
      "closed_time": "2016-05-25 00:49:48"
    },
    {
      "id": 126,
      "billable_in_bytes": 4000000000,
      "billable_out_bytes": 4000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-03-25 00:49:48",
      "closed_time": "2016-04-25 00:49:48"
    },
    {
      "id": 125,
      "billable_in_bytes": 3000000000,
      "billable_out_bytes": 3000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-02-25 00:49:48",
      "closed_time": "2016-03-25 00:49:48"
    },
    {
      "id": 124,
      "billable_in_bytes": 2000000000,
      "billable_out_bytes": 2000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2016-01-25 00:49:48",
      "closed_time": "2016-02-25 00:49:48"
    },
    {
      "id": 123,
      "billable_in_bytes": 1000000000,
      "billable_out_bytes": 1000000000,
      "free_in_bytes": 0,
      "free_out_bytes": 0,
      "start_time": "2015-12-25 00:49:48",
      "closed_time": "2016-01-25 00:49:48"
    }
  ],
  "paginator": {
    "total_count": 7,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Data_Usage - Get an individual aggregated data usage period for an account

Get the aggregated data usage for an account, by ID.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories/:data_usage_history_id

Parameter

Field Type Description
id Number

The ID of the account

data_usage_history_id Number

The ID of the data usage history

Success 200

Field Type Description
id Number

The ID of the data usage history

billable_in_bytes Number

The number of billable inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

billable_out_bytes Number

The number of billable outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

free_in_bytes Number

The number of free inbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

free_out_bytes Number

The number of free outbound bytes used in the period defined from start_time to close_time. If close_time is null, this is the current period.

start_time DateTime

When the data began to be aggregated (UTC)

closed_time DateTime

When the data aggregation was stopped for this item (UTC.) If null, this data is still open and is for the current billing period.

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 136,
    "billable_in_bytes": 0,
    "billable_out_bytes": 0,
    "free_in_bytes": 0,
    "free_out_bytes": 0,
    "start_time": "2016-06-25 00:51:18",
    "closed_time": null
  }
}

Account_Data_Usage - Get granular account data usage across a time period

Get data usage on an account between two Unix timestamps (seconds since epoch.) Unlike most multi-entry endpoints, data from this endpoint is not paginated, to make consumption of data easier for things like graphing. Data returned from this endpoint will calculate the rate of change over a specific period of time, which is the difference in seconds between the two timestamps, divided by 400 (a mostly arbitrary number chosen to make graphing reasonable, and to keep the query load down.) For example, if you input a time period of 24 hours, the difference in seconds would be 86,400. Divided by 400, this would give 216 seconds rounded up, so you would be provided with 400 data points, showing the rate of change every 1 second in 216 second increments. This endpoint returns an array of series - the success section below describes each series. The data may contain multiple series. Note that the granular data is output in bits rather than bytes for use in typical graphing applications! The total data is output in bytes.

https://example.sonar.software/api/v1/accounts/:id/granular_data_usage/:start_time/:end_time

Parameter

Field Type Description
id Number

The ID of the account.

start_time Number

A Unix timestamp (e.g. 1465238009) with up to microsecond accuracy.

end_time Number

A Unix timestamp (e.g. 1465238010) with up to microsecond accuracy.

Success 200

Field Type Description
granular Object

The granular data, broken down by time. This exists at the top level of the response object. The descriptions below are within this array, until the 'separate' array.

series Array

An array that contains the data broken down by series. This is within the granular object.

data_source_identifier String

A unique identifier for the source of this data. For example, this may be an IP address, a RADIUS username, or some other unique piece of information that signifies what specific source generated this traffic.

data_source_parent String

A unique identifier for the device that provided this data. For example, this may reference a RADIUS server, or some type of inline device.

data_type String

The type of data (e.g. HTTP, SSH, ICMP) - typically, this will be the localized string 'Unknown', unless you are feeding in more specific data categories.

in Object

An object where the property is a Unix timestamp, and the value is the amount of data inbound in bits. If your rate of change window is greater than a minute, it is possible that these values will be floats due to the mathematical calculations performed to calculate the rate of change. Please note that the data is the rate of change between the last reading and the current one, and Sonar will attempt to keep the number of entries at 400, so values will change as the window size changes. The most granular spacing returned is 1 minute, so for the most precise data, you can request it in 400 minute windows.

out Object

An object where the property is a Unix timestamp timestamp, and the value is the amount of data outbound in bits. If your rate of change window is greater than a minute, it is possible that these values will be floats due to the mathematical calculations performed to calculate the rate of change. Please note that the data is the rate of change between the last reading and the current one, and Sonar will attempt to keep the number of entries at 400, so values will change as the window size changes. The most granular spacing returned is 1 minute, so for the most precise data, you can request it in 400 minute windows.

totals Object

Totals for all the data in the series array. The values below are in this object.

 HTTP/1.1 200 OK
 {
  "data": {
    "granular": {
      "series": [
        {
          "data_source_identifier": "145.214.83.54",
          "data_source_parent": "Anderson-Vandervort",
          "data_type": "Call of Duty",
          "in": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 217138288,
            "1467103042": 145308376,
            "1467104280": 307148776,
            "1467105518": 544508376,
            "1467106756": 0,
            "1467107994": 420432560,
            "1467109232": 0,
            "1467110470": 109454664,
            "1467111708": 182808536,
            "1467112946": 158426472,
            "1467114184": 819848064,
            "1467115422": 0,
            "1467117898": 301536480,
            "1467119136": 0,
            "1467120374": 722331496,
            "1467121612": 827977224,
            "1467124088": 110407840,
            "1467125326": 762285888,
            "1467126564": 861812776,
            "1467129040": 285242608,
            "1467130278": 911441656,
            "1467131516": 0,
            "1467132754": 660007232,
            "1467135230": 138487544,
            "1467136468": 545750880,
            "1467138944": 0,
            "1467140182": 32555352,
            "1467141420": 0,
            "1467143896": 400100064,
            "1467146372": 0,
            "1467147610": 821975776,
            "1467148848": 151347480,
            "1467150086": 0,
            "1467151324": 572727688,
            "1467152562": 0,
            "1467153800": 0,
            "1467155038": 228804672,
            "1467156276": 0,
            "1467157514": 807192432,
            "1467158752": 996707992,
            "1467159990": 777985992,
            "1467161228": 0,
            "1467162466": 295126192,
            "1467164942": 881194744,
            "1467166180": 942820872,
            "1467167418": 880257936,
            "1467168656": 0,
            "1467169894": 0,
            "1467171132": 396878992,
            "1467172370": 279056800,
            "1467173608": 111492104,
            "1467174846": 819713520,
            "1467176084": 975066904,
            "1467177322": 980927904,
            "1467178560": 619864240,
            "1467182274": 344976544,
            "1467183512": 920085688,
            "1467184750": 0,
            "1467187226": 664613584,
            "1467188464": 0,
            "1467189702": 33572808,
            "1467190940": 0,
            "1467192178": 641773848,
            "1467194654": 241669080,
            "1467195892": 126998536,
            "1467198368": 784293832,
            "1467199606": 966677656,
            "1467200844": 0,
            "1467202082": 677646040,
            "1467203320": 1012206728,
            "1467204558": 439831432,
            "1467205796": 0,
            "1467207034": 49039992,
            "1467208272": 195231264,
            "1467209510": 873323560,
            "1467210748": 856915632,
            "1467211986": 0,
            "1467213224": 0,
            "1467215700": 79292928,
            "1467216938": 713658056,
            "1467218176": 0,
            "1467219414": 685737920,
            "1467220652": 0,
            "1467221890": 0,
            "1467223128": 360265952,
            "1467224366": 0,
            "1467225604": 434273728,
            "1467226842": 0,
            "1467228080": 216324504,
            "1467229318": 0,
            "1467230556": 851006360,
            "1467233032": 334718240,
            "1467234270": 854355168,
            "1467235508": 779245856,
            "1467236746": 0,
            "1467237984": 0,
            "1467239222": 0,
            "1467240460": 542660304,
            "1467241698": 782791880,
            "1467242936": 763122896,
            "1467244174": 408041888,
            "1467245412": 0,
            "1467246650": 363461488,
            "1467247888": 0,
            "1467249126": 0,
            "1467251602": 702242904,
            "1467252840": 665581824,
            "1467254078": 912337056,
            "1467255316": 607106448,
            "1467256554": 212773648,
            "1467259030": 253847088,
            "1467260268": 272247312,
            "1467261506": 889458392,
            "1467262744": 0,
            "1467265220": 984081728,
            "1467267696": 0,
            "1467268934": 580968592,
            "1467270172": 891309648,
            "1467272648": 0,
            "1467273886": 247251968,
            "1467275124": 0,
            "1467276362": 676973864,
            "1467277600": 1005099440,
            "1467278838": 928361760,
            "1467280076": 627488416,
            "1467281314": 1011717416,
            "1467283790": 0,
            "1467285028": 524871776,
            "1467286266": 663324224,
            "1467288742": 342366880,
            "1467291218": 877844064,
            "1467292456": 663320864,
            "1467293694": 884311608,
            "1467296170": 0,
            "1467297408": 1041119216,
            "1467298646": 897873392,
            "1467301122": 0,
            "1467302360": 0,
            "1467303598": 801878496,
            "1467304836": 903899368,
            "1467307312": 0,
            "1467309788": 256131072,
            "1467311026": 225189000,
            "1467312264": 92491960,
            "1467313502": 774727352,
            "1467314740": 975401880,
            "1467315978": 885190984,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          },
          "out": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 23459856,
            "1467103042": 21061032,
            "1467104280": 37073168,
            "1467105518": 56226824,
            "1467106756": 0,
            "1467107994": 61999544,
            "1467109232": 0,
            "1467110470": 0,
            "1467111708": 26790872,
            "1467112946": 29429144,
            "1467114184": 85163296,
            "1467115422": 0,
            "1467117898": 28196368,
            "1467119136": 0,
            "1467120374": 46199384,
            "1467121612": 83895888,
            "1467124088": 19672208,
            "1467125326": 84634040,
            "1467126564": 93244928,
            "1467129040": 5242248,
            "1467130278": 84587584,
            "1467131516": 0,
            "1467132754": 78679480,
            "1467135230": 19779312,
            "1467136468": 65770072,
            "1467138944": 2969624,
            "1467140182": 9410496,
            "1467141420": 5006496,
            "1467143896": 43782360,
            "1467146372": 0,
            "1467147610": 91490672,
            "1467148848": 13331008,
            "1467150086": 0,
            "1467151324": 60490624,
            "1467152562": 0,
            "1467153800": 0,
            "1467155038": 19772136,
            "1467156276": 0,
            "1467157514": 74968816,
            "1467158752": 89856672,
            "1467159990": 73784992,
            "1467161228": 0,
            "1467162466": 8892048,
            "1467164942": 85294624,
            "1467166180": 102953304,
            "1467167418": 90734512,
            "1467168656": 0,
            "1467169894": 5938256,
            "1467171132": 28965600,
            "1467172370": 26839288,
            "1467173608": 4386472,
            "1467174846": 69137752,
            "1467176084": 96880832,
            "1467177322": 77810424,
            "1467178560": 66080776,
            "1467182274": 16460024,
            "1467183512": 78225488,
            "1467184750": 0,
            "1467187226": 68038464,
            "1467188464": 0,
            "1467189702": 7160584,
            "1467190940": 0,
            "1467192178": 70475368,
            "1467194654": 2375312,
            "1467195892": 13846192,
            "1467198368": 62233504,
            "1467199606": 88877712,
            "1467200844": 0,
            "1467202082": 72632672,
            "1467203320": 108654808,
            "1467204558": 61242720,
            "1467205796": 0,
            "1467207034": 0,
            "1467208272": 18418000,
            "1467209510": 87725608,
            "1467210748": 78836944,
            "1467211986": 0,
            "1467213224": 0,
            "1467215700": 1117832,
            "1467216938": 73283768,
            "1467218176": 0,
            "1467219414": 80848960,
            "1467220652": 0,
            "1467221890": 33970832,
            "1467223128": 23287944,
            "1467224366": 0,
            "1467225604": 23585168,
            "1467226842": 0,
            "1467228080": 28487128,
            "1467229318": 4977736,
            "1467230556": 90171064,
            "1467233032": 27683016,
            "1467234270": 77534464,
            "1467235508": 85958008,
            "1467236746": 0,
            "1467237984": 0,
            "1467239222": 0,
            "1467240460": 73044880,
            "1467241698": 91222816,
            "1467242936": 74177608,
            "1467244174": 43850312,
            "1467245412": 0,
            "1467246650": 33914504,
            "1467247888": 0,
            "1467249126": 0,
            "1467251602": 80564680,
            "1467252840": 96260840,
            "1467254078": 116959008,
            "1467255316": 64164432,
            "1467256554": 6485688,
            "1467259030": 17960064,
            "1467260268": 26443576,
            "1467261506": 94495904,
            "1467262744": 0,
            "1467265220": 108246872,
            "1467267696": 0,
            "1467268934": 42579240,
            "1467270172": 82041496,
            "1467272648": 0,
            "1467273886": 26091632,
            "1467275124": 0,
            "1467276362": 66722544,
            "1467277600": 102038904,
            "1467278838": 85439928,
            "1467280076": 68357456,
            "1467281314": 120435760,
            "1467283790": 0,
            "1467285028": 56439352,
            "1467286266": 80184016,
            "1467288742": 30790496,
            "1467291218": 81895720,
            "1467292456": 78105344,
            "1467293694": 109212160,
            "1467296170": 0,
            "1467297408": 114766912,
            "1467298646": 105400656,
            "1467301122": 0,
            "1467302360": 0,
            "1467303598": 63503480,
            "1467304836": 93109752,
            "1467307312": 0,
            "1467309788": 39355128,
            "1467311026": 16244976,
            "1467312264": 0,
            "1467313502": 66977688,
            "1467314740": 96243760,
            "1467315978": 79732280,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          }
        },
        {
          "data_source_identifier": "218.234.174.22",
          "data_source_parent": "Rowe LLC",
          "data_type": "SSL",
          "in": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 241497856,
            "1467103042": 238027520,
            "1467104280": 0,
            "1467105518": 954729928,
            "1467106756": 794414800,
            "1467107994": 875005320,
            "1467109232": 865233216,
            "1467110470": 0,
            "1467111708": 0,
            "1467112946": 151266624,
            "1467114184": 24491184,
            "1467115422": 552629720,
            "1467117898": 0,
            "1467119136": 554519288,
            "1467120374": 644687696,
            "1467121612": 535262648,
            "1467124088": 8266816,
            "1467125326": 875103392,
            "1467126564": 0,
            "1467129040": 317138456,
            "1467130278": 862225208,
            "1467131516": 912205512,
            "1467132754": 0,
            "1467135230": 0,
            "1467136468": 715514632,
            "1467138944": 0,
            "1467140182": 1633792,
            "1467141420": 209544328,
            "1467143896": 384091240,
            "1467146372": 488261120,
            "1467147610": 0,
            "1467148848": 441910432,
            "1467150086": 843532920,
            "1467151324": 0,
            "1467152562": 910990504,
            "1467153800": 897000928,
            "1467155038": 0,
            "1467156276": 393010928,
            "1467157514": 889528304,
            "1467158752": 0,
            "1467159990": 0,
            "1467161228": 661604080,
            "1467162466": 0,
            "1467164942": 487196568,
            "1467166180": 138329160,
            "1467167418": 0,
            "1467168656": 751713000,
            "1467169894": 945302280,
            "1467171132": 657959136,
            "1467172370": 744025872,
            "1467173608": 0,
            "1467174846": 516615376,
            "1467176084": 0,
            "1467177322": 496411296,
            "1467178560": 854530032,
            "1467182274": 741389696,
            "1467183512": 0,
            "1467184750": 365575632,
            "1467187226": 76781936,
            "1467188464": 479329088,
            "1467189702": 921174272,
            "1467190940": 811543176,
            "1467192178": 626420896,
            "1467194654": 357743344,
            "1467195892": 0,
            "1467198368": 279658312,
            "1467199606": 0,
            "1467200844": 247948496,
            "1467202082": 713357184,
            "1467203320": 870829888,
            "1467204558": 0,
            "1467205796": 5569048,
            "1467207034": 0,
            "1467208272": 72400600,
            "1467209510": 45927544,
            "1467210748": 30932992,
            "1467211986": 158675552,
            "1467213224": 393533904,
            "1467215700": 0,
            "1467216938": 637265192,
            "1467218176": 754524808,
            "1467219414": 813787976,
            "1467220652": 567888528,
            "1467221890": 0,
            "1467223128": 942237544,
            "1467224366": 976443536,
            "1467225604": 0,
            "1467226842": 0,
            "1467228080": 262707640,
            "1467229318": 0,
            "1467230556": 0,
            "1467233032": 808759408,
            "1467234270": 959167688,
            "1467235508": 0,
            "1467236746": 0,
            "1467237984": 136756576,
            "1467239222": 923578640,
            "1467240460": 911812616,
            "1467241698": 0,
            "1467242936": 91416816,
            "1467244174": 0,
            "1467245412": 73593648,
            "1467246650": 246030680,
            "1467247888": 51180464,
            "1467249126": 768933728,
            "1467251602": 0,
            "1467252840": 606103568,
            "1467254078": 0,
            "1467255316": 411153424,
            "1467256554": 277204928,
            "1467259030": 728589144,
            "1467260268": 0,
            "1467261506": 137265712,
            "1467262744": 809327560,
            "1467265220": 0,
            "1467267696": 17492920,
            "1467268934": 827414064,
            "1467270172": 0,
            "1467272648": 338329864,
            "1467273886": 898290176,
            "1467275124": 917279656,
            "1467276362": 0,
            "1467277600": 0,
            "1467278838": 871703088,
            "1467280076": 710188952,
            "1467281314": 0,
            "1467283790": 664007448,
            "1467285028": 804198240,
            "1467286266": 0,
            "1467288742": 53393744,
            "1467291218": 737036000,
            "1467292456": 80661032,
            "1467293694": 0,
            "1467296170": 742478208,
            "1467297408": 777910336,
            "1467298646": 444120600,
            "1467301122": 926272536,
            "1467302360": 1011730232,
            "1467303598": 573550096,
            "1467304836": 0,
            "1467307312": 831698528,
            "1467309788": 0,
            "1467311026": 0,
            "1467312264": 35359936,
            "1467313502": 534446672,
            "1467314740": 0,
            "1467315978": 520835832,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          },
          "out": {
            "1467080758": 0,
            "1467081996": 0,
            "1467083234": 0,
            "1467084472": 0,
            "1467085710": 0,
            "1467086948": 0,
            "1467088186": 0,
            "1467089424": 0,
            "1467090662": 0,
            "1467091900": 0,
            "1467093138": 0,
            "1467094376": 0,
            "1467095614": 0,
            "1467096852": 0,
            "1467098090": 0,
            "1467099328": 0,
            "1467100566": 0,
            "1467101804": 31826464,
            "1467103042": 21794824,
            "1467104280": 0,
            "1467105518": 79911632,
            "1467106756": 65303888,
            "1467107994": 92015568,
            "1467109232": 99799696,
            "1467110470": 0,
            "1467111708": 0,
            "1467112946": 31622696,
            "1467114184": 0,
            "1467115422": 62625688,
            "1467117898": 0,
            "1467119136": 69246664,
            "1467120374": 86943576,
            "1467121612": 56117368,
            "1467124088": 8430776,
            "1467125326": 84747712,
            "1467126564": 0,
            "1467129040": 36480632,
            "1467130278": 77877496,
            "1467131516": 74126696,
            "1467132754": 0,
            "1467135230": 0,
            "1467136468": 69078816,
            "1467138944": 0,
            "1467140182": 5218968,
            "1467141420": 20327760,
            "1467143896": 35429664,
            "1467146372": 42652160,
            "1467147610": 0,
            "1467148848": 49718032,
            "1467150086": 90606272,
            "1467151324": 0,
            "1467152562": 100804544,
            "1467153800": 87413496,
            "1467155038": 0,
            "1467156276": 23493928,
            "1467157514": 60484176,
            "1467158752": 317480,
            "1467159990": 0,
            "1467161228": 40529392,
            "1467162466": 10359568,
            "1467164942": 55929096,
            "1467166180": 17257856,
            "1467167418": 0,
            "1467168656": 92946400,
            "1467169894": 83674176,
            "1467171132": 58613688,
            "1467172370": 80019712,
            "1467173608": 0,
            "1467174846": 39068048,
            "1467176084": 0,
            "1467177322": 44167472,
            "1467178560": 85493272,
            "1467182274": 74313848,
            "1467183512": 0,
            "1467184750": 26876928,
            "1467187226": 15515744,
            "1467188464": 47704832,
            "1467189702": 78234096,
            "1467190940": 87350648,
            "1467192178": 74592368,
            "1467194654": 48197008,
            "1467195892": 0,
            "1467198368": 45893448,
            "1467199606": 0,
            "1467200844": 38539784,
            "1467202082": 82040760,
            "1467203320": 97426848,
            "1467204558": 0,
            "1467205796": 0,
            "1467207034": 0,
            "1467208272": 15427936,
            "1467209510": 24524416,
            "1467210748": 13229144,
            "1467211986": 0,
            "1467213224": 37926848,
            "1467215700": 0,
            "1467216938": 76580480,
            "1467218176": 72352496,
            "1467219414": 91127296,
            "1467220652": 53883936,
            "1467221890": 0,
            "1467223128": 90196272,
            "1467224366": 86683880,
            "1467225604": 0,
            "1467226842": 5169304,
            "1467228080": 16213712,
            "1467229318": 9663464,
            "1467230556": 0,
            "1467233032": 65308160,
            "1467234270": 96469432,
            "1467235508": 0,
            "1467236746": 3273648,
            "1467237984": 4758136,
            "1467239222": 84232024,
            "1467240460": 87098360,
            "1467241698": 0,
            "1467242936": 157320,
            "1467244174": 14256680,
            "1467245412": 4490592,
            "1467246650": 17846656,
            "1467247888": 0,
            "1467249126": 70157680,
            "1467251602": 0,
            "1467252840": 67316888,
            "1467254078": 0,
            "1467255316": 54744096,
            "1467256554": 23767120,
            "1467259030": 70607368,
            "1467260268": 0,
            "1467261506": 21301864,
            "1467262744": 66224416,
            "1467265220": 0,
            "1467267696": 42544816,
            "1467268934": 75615304,
            "1467270172": 0,
            "1467272648": 2739480,
            "1467273886": 80519424,
            "1467275124": 84592232,
            "1467276362": 0,
            "1467277600": 0,
            "1467278838": 89690992,
            "1467280076": 80328128,
            "1467281314": 0,
            "1467283790": 96126096,
            "1467285028": 84160928,
            "1467286266": 0,
            "1467288742": 5069208,
            "1467291218": 77109912,
            "1467292456": 0,
            "1467293694": 0,
            "1467296170": 82970552,
            "1467297408": 81700800,
            "1467298646": 39722672,
            "1467301122": 79082352,
            "1467302360": 102078952,
            "1467303598": 78483144,
            "1467304836": 0,
            "1467307312": 101075704,
            "1467309788": 0,
            "1467311026": 9440736,
            "1467312264": 4604032,
            "1467313502": 72199016,
            "1467314740": 0,
            "1467315978": 46107856,
            "1467319692": 0,
            "1467320930": 0,
            "1467322168": 0,
            "1467323406": 0,
            "1467324644": 0,
            "1467325882": 0,
            "1467327120": 0,
            "1467328358": 0,
            "1467329596": 0,
            "1467330834": 0,
            "1467332072": 0,
            "1467333310": 0,
            "1467334548": 0,
            "1467335786": 0,
            "1467337024": 0,
            "1467338262": 0,
            "1467339500": 0,
            "1467340738": 0,
            "1467341976": 0,
            "1467343214": 0,
            "1467344452": 0,
            "1467345690": 0,
            "1467346928": 0,
            "1467348166": 0,
            "1467349404": 0,
            "1467350642": 0,
            "1467351880": 0,
            "1467353118": 0,
            "1467354356": 0,
            "1467355594": 0,
            "1467356832": 0,
            "1467358070": 0,
            "1467359308": 0,
            "1467360546": 0,
            "1467361784": 0,
            "1467363022": 0,
            "1467364260": 0,
            "1467365498": 0,
            "1467366736": 0,
            "1467367974": 0,
            "1467369212": 0,
            "1467370450": 0,
            "1467371688": 0,
            "1467372926": 0,
            "1467374164": 0,
            "1467375402": 0,
            "1467376640": 0,
            "1467377878": 0,
            "1467379116": 0,
            "1467380354": 0,
            "1467381592": 0,
            "1467382830": 0,
            "1467384068": 0,
            "1467385306": 0,
            "1467386544": 0,
            "1467387782": 0,
            "1467389020": 0,
            "1467390258": 0
          }
        }
      ],
      "totals": {
        "in": {
          "1467080758": 0,
          "1467081996": 0,
          "1467083234": 0,
          "1467084472": 0,
          "1467085710": 0,
          "1467086948": 0,
          "1467088186": 0,
          "1467089424": 0,
          "1467090662": 0,
          "1467091900": 0,
          "1467093138": 0,
          "1467094376": 0,
          "1467095614": 0,
          "1467096852": 0,
          "1467098090": 0,
          "1467099328": 0,
          "1467100566": 0,
          "1467101804": 458636144,
          "1467103042": 383335896,
          "1467104280": 307148776,
          "1467105518": 1499238304,
          "1467106756": 794414800,
          "1467107994": 1295437880,
          "1467109232": 865233216,
          "1467110470": 109454664,
          "1467111708": 182808536,
          "1467112946": 309693096,
          "1467114184": 844339248,
          "1467115422": 552629720,
          "1467117898": 301536480,
          "1467119136": 554519288,
          "1467120374": 1367019192,
          "1467121612": 1363239872,
          "1467124088": 118674656,
          "1467125326": 1637389280,
          "1467126564": 861812776,
          "1467129040": 602381064,
          "1467130278": 1773666864,
          "1467131516": 912205512,
          "1467132754": 660007232,
          "1467135230": 138487544,
          "1467136468": 1261265512,
          "1467138944": 0,
          "1467140182": 34189144,
          "1467141420": 209544328,
          "1467143896": 784191304,
          "1467146372": 488261120,
          "1467147610": 821975776,
          "1467148848": 593257912,
          "1467150086": 843532920,
          "1467151324": 572727688,
          "1467152562": 910990504,
          "1467153800": 897000928,
          "1467155038": 228804672,
          "1467156276": 393010928,
          "1467157514": 1696720736,
          "1467158752": 996707992,
          "1467159990": 777985992,
          "1467161228": 661604080,
          "1467162466": 295126192,
          "1467164942": 1368391312,
          "1467166180": 1081150032,
          "1467167418": 880257936,
          "1467168656": 751713000,
          "1467169894": 945302280,
          "1467171132": 1054838128,
          "1467172370": 1023082672,
          "1467173608": 111492104,
          "1467174846": 1336328896,
          "1467176084": 975066904,
          "1467177322": 1477339200,
          "1467178560": 1474394272,
          "1467182274": 1086366240,
          "1467183512": 920085688,
          "1467184750": 365575632,
          "1467187226": 741395520,
          "1467188464": 479329088,
          "1467189702": 954747080,
          "1467190940": 811543176,
          "1467192178": 1268194744,
          "1467194654": 599412424,
          "1467195892": 126998536,
          "1467198368": 1063952144,
          "1467199606": 966677656,
          "1467200844": 247948496,
          "1467202082": 1391003224,
          "1467203320": 1883036616,
          "1467204558": 439831432,
          "1467205796": 5569048,
          "1467207034": 49039992,
          "1467208272": 267631864,
          "1467209510": 919251104,
          "1467210748": 887848624,
          "1467211986": 158675552,
          "1467213224": 393533904,
          "1467215700": 79292928,
          "1467216938": 1350923248,
          "1467218176": 754524808,
          "1467219414": 1499525896,
          "1467220652": 567888528,
          "1467221890": 0,
          "1467223128": 1302503496,
          "1467224366": 976443536,
          "1467225604": 434273728,
          "1467226842": 0,
          "1467228080": 479032144,
          "1467229318": 0,
          "1467230556": 851006360,
          "1467233032": 1143477648,
          "1467234270": 1813522856,
          "1467235508": 779245856,
          "1467236746": 0,
          "1467237984": 136756576,
          "1467239222": 923578640,
          "1467240460": 1454472920,
          "1467241698": 782791880,
          "1467242936": 854539712,
          "1467244174": 408041888,
          "1467245412": 73593648,
          "1467246650": 609492168,
          "1467247888": 51180464,
          "1467249126": 768933728,
          "1467251602": 702242904,
          "1467252840": 1271685392,
          "1467254078": 912337056,
          "1467255316": 1018259872,
          "1467256554": 489978576,
          "1467259030": 982436232,
          "1467260268": 272247312,
          "1467261506": 1026724104,
          "1467262744": 809327560,
          "1467265220": 984081728,
          "1467267696": 17492920,
          "1467268934": 1408382656,
          "1467270172": 891309648,
          "1467272648": 338329864,
          "1467273886": 1145542144,
          "1467275124": 917279656,
          "1467276362": 676973864,
          "1467277600": 1005099440,
          "1467278838": 1800064848,
          "1467280076": 1337677368,
          "1467281314": 1011717416,
          "1467283790": 664007448,
          "1467285028": 1329070016,
          "1467286266": 663324224,
          "1467288742": 395760624,
          "1467291218": 1614880064,
          "1467292456": 743981896,
          "1467293694": 884311608,
          "1467296170": 742478208,
          "1467297408": 1819029552,
          "1467298646": 1341993992,
          "1467301122": 926272536,
          "1467302360": 1011730232,
          "1467303598": 1375428592,
          "1467304836": 903899368,
          "1467307312": 831698528,
          "1467309788": 256131072,
          "1467311026": 225189000,
          "1467312264": 127851896,
          "1467313502": 1309174024,
          "1467314740": 975401880,
          "1467315978": 1406026816,
          "1467319692": 0,
          "1467320930": 0,
          "1467322168": 0,
          "1467323406": 0,
          "1467324644": 0,
          "1467325882": 0,
          "1467327120": 0,
          "1467328358": 0,
          "1467329596": 0,
          "1467330834": 0,
          "1467332072": 0,
          "1467333310": 0,
          "1467334548": 0,
          "1467335786": 0,
          "1467337024": 0,
          "1467338262": 0,
          "1467339500": 0,
          "1467340738": 0,
          "1467341976": 0,
          "1467343214": 0,
          "1467344452": 0,
          "1467345690": 0,
          "1467346928": 0,
          "1467348166": 0,
          "1467349404": 0,
          "1467350642": 0,
          "1467351880": 0,
          "1467353118": 0,
          "1467354356": 0,
          "1467355594": 0,
          "1467356832": 0,
          "1467358070": 0,
          "1467359308": 0,
          "1467360546": 0,
          "1467361784": 0,
          "1467363022": 0,
          "1467364260": 0,
          "1467365498": 0,
          "1467366736": 0,
          "1467367974": 0,
          "1467369212": 0,
          "1467370450": 0,
          "1467371688": 0,
          "1467372926": 0,
          "1467374164": 0,
          "1467375402": 0,
          "1467376640": 0,
          "1467377878": 0,
          "1467379116": 0,
          "1467380354": 0,
          "1467381592": 0,
          "1467382830": 0,
          "1467384068": 0,
          "1467385306": 0,
          "1467386544": 0,
          "1467387782": 0,
          "1467389020": 0,
          "1467390258": 0
        },
        "out": {
          "1467080758": 0,
          "1467081996": 0,
          "1467083234": 0,
          "1467084472": 0,
          "1467085710": 0,
          "1467086948": 0,
          "1467088186": 0,
          "1467089424": 0,
          "1467090662": 0,
          "1467091900": 0,
          "1467093138": 0,
          "1467094376": 0,
          "1467095614": 0,
          "1467096852": 0,
          "1467098090": 0,
          "1467099328": 0,
          "1467100566": 0,
          "1467101804": 55286320,
          "1467103042": 42855856,
          "1467104280": 37073168,
          "1467105518": 136138456,
          "1467106756": 65303888,
          "1467107994": 154015112,
          "1467109232": 99799696,
          "1467110470": 0,
          "1467111708": 26790872,
          "1467112946": 61051840,
          "1467114184": 85163296,
          "1467115422": 62625688,
          "1467117898": 28196368,
          "1467119136": 69246664,
          "1467120374": 133142960,
          "1467121612": 140013256,
          "1467124088": 28102984,
          "1467125326": 169381752,
          "1467126564": 93244928,
          "1467129040": 41722880,
          "1467130278": 162465080,
          "1467131516": 74126696,
          "1467132754": 78679480,
          "1467135230": 19779312,
          "1467136468": 134848888,
          "1467138944": 2969624,
          "1467140182": 14629464,
          "1467141420": 25334256,
          "1467143896": 79212024,
          "1467146372": 42652160,
          "1467147610": 91490672,
          "1467148848": 63049040,
          "1467150086": 90606272,
          "1467151324": 60490624,
          "1467152562": 100804544,
          "1467153800": 87413496,
          "1467155038": 19772136,
          "1467156276": 23493928,
          "1467157514": 135452992,
          "1467158752": 90174152,
          "1467159990": 73784992,
          "1467161228": 40529392,
          "1467162466": 19251616,
          "1467164942": 141223720,
          "1467166180": 120211160,
          "1467167418": 90734512,
          "1467168656": 92946400,
          "1467169894": 89612432,
          "1467171132": 87579288,
          "1467172370": 106859000,
          "1467173608": 4386472,
          "1467174846": 108205800,
          "1467176084": 96880832,
          "1467177322": 121977896,
          "1467178560": 151574048,
          "1467182274": 90773872,
          "1467183512": 78225488,
          "1467184750": 26876928,
          "1467187226": 83554208,
          "1467188464": 47704832,
          "1467189702": 85394680,
          "1467190940": 87350648,
          "1467192178": 145067736,
          "1467194654": 50572320,
          "1467195892": 13846192,
          "1467198368": 108126952,
          "1467199606": 88877712,
          "1467200844": 38539784,
          "1467202082": 154673432,
          "1467203320": 206081656,
          "1467204558": 61242720,
          "1467205796": 0,
          "1467207034": 0,
          "1467208272": 33845936,
          "1467209510": 112250024,
          "1467210748": 92066088,
          "1467211986": 0,
          "1467213224": 37926848,
          "1467215700": 1117832,
          "1467216938": 149864248,
          "1467218176": 72352496,
          "1467219414": 171976256,
          "1467220652": 53883936,
          "1467221890": 33970832,
          "1467223128": 113484216,
          "1467224366": 86683880,
          "1467225604": 23585168,
          "1467226842": 5169304,
          "1467228080": 44700840,
          "1467229318": 14641200,
          "1467230556": 90171064,
          "1467233032": 92991176,
          "1467234270": 174003896,
          "1467235508": 85958008,
          "1467236746": 3273648,
          "1467237984": 4758136,
          "1467239222": 84232024,
          "1467240460": 160143240,
          "1467241698": 91222816,
          "1467242936": 74334928,
          "1467244174": 58106992,
          "1467245412": 4490592,
          "1467246650": 51761160,
          "1467247888": 0,
          "1467249126": 70157680,
          "1467251602": 80564680,
          "1467252840": 163577728,
          "1467254078": 116959008,
          "1467255316": 118908528,
          "1467256554": 30252808,
          "1467259030": 88567432,
          "1467260268": 26443576,
          "1467261506": 115797768,
          "1467262744": 66224416,
          "1467265220": 108246872,
          "1467267696": 42544816,
          "1467268934": 118194544,
          "1467270172": 82041496,
          "1467272648": 2739480,
          "1467273886": 106611056,
          "1467275124": 84592232,
          "1467276362": 66722544,
          "1467277600": 102038904,
          "1467278838": 175130920,
          "1467280076": 148685584,
          "1467281314": 120435760,
          "1467283790": 96126096,
          "1467285028": 140600280,
          "1467286266": 80184016,
          "1467288742": 35859704,
          "1467291218": 159005632,
          "1467292456": 78105344,
          "1467293694": 109212160,
          "1467296170": 82970552,
          "1467297408": 196467712,
          "1467298646": 145123328,
          "1467301122": 79082352,
          "1467302360": 102078952,
          "1467303598": 141986624,
          "1467304836": 93109752,
          "1467307312": 101075704,
          "1467309788": 39355128,
          "1467311026": 25685712,
          "1467312264": 4604032,
          "1467313502": 139176704,
          "1467314740": 96243760,
          "1467315978": 125840136,
          "1467319692": 0,
          "1467320930": 0,
          "1467322168": 0,
          "1467323406": 0,
          "1467324644": 0,
          "1467325882": 0,
          "1467327120": 0,
          "1467328358": 0,
          "1467329596": 0,
          "1467330834": 0,
          "1467332072": 0,
          "1467333310": 0,
          "1467334548": 0,
          "1467335786": 0,
          "1467337024": 0,
          "1467338262": 0,
          "1467339500": 0,
          "1467340738": 0,
          "1467341976": 0,
          "1467343214": 0,
          "1467344452": 0,
          "1467345690": 0,
          "1467346928": 0,
          "1467348166": 0,
          "1467349404": 0,
          "1467350642": 0,
          "1467351880": 0,
          "1467353118": 0,
          "1467354356": 0,
          "1467355594": 0,
          "1467356832": 0,
          "1467358070": 0,
          "1467359308": 0,
          "1467360546": 0,
          "1467361784": 0,
          "1467363022": 0,
          "1467364260": 0,
          "1467365498": 0,
          "1467366736": 0,
          "1467367974": 0,
          "1467369212": 0,
          "1467370450": 0,
          "1467371688": 0,
          "1467372926": 0,
          "1467374164": 0,
          "1467375402": 0,
          "1467376640": 0,
          "1467377878": 0,
          "1467379116": 0,
          "1467380354": 0,
          "1467381592": 0,
          "1467382830": 0,
          "1467384068": 0,
          "1467385306": 0,
          "1467386544": 0,
          "1467387782": 0,
          "1467389020": 0,
          "1467390258": 0
        }
      }
    },
    "totals": [
      {
        "data_source_identifier": "145.214.83.54",
        "data_source_parent": "Anderson-Vandervort",
        "data_type": "Call of Duty",
        "totals": {
          "total_in": 855408253,
          "total_out": 89574386,
          "combined_total": 944982639
        }
      },
      {
        "data_source_identifier": "218.234.174.22",
        "data_source_parent": "Rowe LLC",
        "data_type": "SSL",
        "totals": {
          "total_in": 861366560,
          "total_out": 88558681,
          "combined_total": 949925241
        }
      }
    ]
  }
}

Account_Data_Usage - Update current aggregated data usage for an account

Modify the current billing period data usage. This can only be performed on the most recent, unclosed data usage history. You should not use this to add real, current usage to an account, instead use the Add granular data usage to an account endpoint. This is only to correct mistakes in billable/free usage. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:id/data_usage_histories

Parameter

Field Type Description
id Number

The ID of the account

billable_in_bytes Number

The number of billable inbound bytes used in the current period.

billable_out_bytes Number

The number of billable outbound bytes used in the current period.

free_in_bytes Number

The number of free inbound bytes used in the current period.

free_out_bytes Number

The number of free outbound bytes used in the current period.

Success 200

Field Type Description
id Number

The ID of the data usage history

billable_in_bytes Number

The number of billable inbound bytes used in the current period.

billable_out_bytes Number

The number of billable outbound bytes used in the current period.

free_in_bytes Number

The number of free inbound bytes used in the current period.

free_out_bytes Number

The number of free outbound bytes used in the current period.

start_time DateTime

When the data began to be aggregated (UTC)

closed_time DateTime

When the data aggregation was stopped for this item (UTC.) Will always be null from this endpoint.

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 136,
    "billable_in_bytes": 0,
    "billable_out_bytes": 0,
    "free_in_bytes": 0,
    "free_out_bytes": 0,
    "start_time": "2016-06-25 00:51:18",
    "closed_time": null
  }
}

Account IP Addresses

Account_IP_Addresses - Assign an IP to an account

This endpoint allows you to assign IPv4/IPv6 assignments to an account, a RADIUS account on an account, an uninventoried MAC address, or an inventory model field on an account. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field Type Description
id Number

The ID of the account

subnet String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.

assigned_entity String

The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.)

Allowed values: "accounts", "inventory_items", "radius_accounts", "non_inventoried_mac_addresses"

assigned_id optional Number

The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.

inventory_item_field_id optional Number

If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.

description optional String

Optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service that the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "inventory_item_field_id": null,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null,
       "soft": false
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Assign an IP to an account

This endpoint allows you to assign IPv4/IPv6 assignments to an account, a RADIUS account on an account, an uninventoried MAC address, or an inventory model field on an account. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field Type Description
id Number

The ID of the account

subnet String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.

assigned_entity String

The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.)

Allowed values: "accounts", "inventory_items", "radius_accounts", "non_inventoried_mac_addresses"

assigned_id optional Number

The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.

inventory_item_field_id optional Number

If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning) if you'd like to bind the IP directly to an interface. If you don't supply this when assigned_entity is inventory_items, then the IP will be attached directly to the inventory item.

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.

description optional String

Optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service that the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "inventory_item_field_id": null,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null,
       "soft": false
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Assign an IP to an account

This endpoint allows you to assign IPv4/IPv6 assignments to an account, a RADIUS account on an account, an uninventoried MAC address, or an inventory model field on an account. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field Type Description
id Number

The ID of the account

subnet String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32. If this is in a pool, and is assigned to a RADIUS account, it will be written as a Framed-IP-Address. Otherwise, it will be written as a Framed-Route.

assigned_entity String

The entity to assign this to - the account directly, a RADIUS account on the account, an inventory item on the account, or a non-inventoried MAC address. You should only use the non-inventoried MAC address option to add an assignment to a device you do not own (e.g. a customer router.)

Allowed values: "accounts", "inventory_items", "radius_accounts", "non_inventoried_mac_addresses"

assigned_id optional Number

The ID of the entity referenced in assigned_entity. If assigned_entity is 'accounts' or 'non_inventoried_mac_addresses', this can be omitted.

inventory_item_field_id optional Number

If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.

description optional String

Optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service that the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
  "data": {
       "id": 8,
       "subnet_id": 1,
       "subnet": "192.168.100.17/32",
       "assigned_entity": "accounts",
       "assigned_id": 1,
       "ip_pool_id": null,
       "account_id": 1,
       "service_id": 4,
       "non_inventoried_mac_address": null,
       "description": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Account_IP_Addresses - Delete IP assignment

Delete an IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the IP assignment could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete this subnet, as other subnets are using it as their next hop."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the account

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
    "data": [
       {
         "id": 1,
         "subnet_id": 1,
         "subnet": "192.168.100.5",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "inventory_item_field_id": null,
         "ip_pool_id": null,
         "account_id": 1,
         "service_id": 4,
         "non_inventoried_mac_address": null,
         "description": null,
         "soft": false
       },
       {
         "id": 2,
         "subnet_id": 1,
         "subnet": "192.168.100.6",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "inventory_item_field_id": null,
         "ip_pool_id": null,
          "account_id": 1,
          "service_id": 4,
          "non_inventoried_mac_address": null,
          "description": null,
          "soft": false
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the account

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
    "data": [
       {
         "id": 1,
         "subnet_id": 1,
         "subnet": "192.168.100.5",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "ip_pool_id": null,
         "account_id": 1,
         "service_id": 4,
         "non_inventoried_mac_address": null,
         "description": null
       },
       {
         "id": 2,
         "subnet_id": 1,
         "subnet": "192.168.100.6",
         "assigned_entity": "accounts",
         "assigned_id": 1,
         "ip_pool_id": null,
          "account_id": 1,
          "service_id": 4,
          "non_inventoried_mac_address": null,
          "description": null
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Account_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 3,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Account_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 3,
     "non_inventoried_mac_address": null,
     "description": null
   }
}

Account_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an account, only the subnet can be changed. If it is on a RADIUS account, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment

subnet optional String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.

assigned_id optional Number

Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If the inventory item is not assigned to the same account as the existing assignment, it will be rejected. If the IP is currently assigned to an inventory_item_field_id and you supply this value and not inventory_item_field_id, the IP will be moved from the field level to the item level.

inventory_item_field_id optional Number

If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format. If this is omitted, an dthe IP is currently associated with an inventory item field, then the IP will be moved from an existing field down to the inventory item level.

description optional String

An optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

make_permanent Boolean

If this is set to true, and the soft property of this IP assignment is currently true, then this will be changed to a permanent assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an account, only the subnet can be changed. If it is on a RADIUS account, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment

subnet optional String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.

assigned_id optional Number

Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same account as the existing assignment, it will also be rejected.

inventory_item_field_id optional Number

If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.

description optional String

An optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

make_permanent Boolean

If this is set to true, and the soft property of this IP assignment is currently true, then this will be changed to a permanent assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null,
     "soft": false
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an account, only the subnet can be changed. If it is on a RADIUS account, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/accounts/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the account

ip_assignment_id Number

The ID of the IP assignment

subnet optional String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a customer/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.

assigned_id optional Number

Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same account as the existing assignment, it will also be rejected.

inventory_item_field_id optional Number

If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).

non_inventoried_mac_address optional String

If the assigned_entity is non_inventoried_mac_addresses, then this should be the MAC address you wish to add, in AA:AA:AA:AA:AA:AA format.

description optional String

An optional description for the assignment

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this IP assignment to. This will affect the address list it is in, if you have address list that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned. If this IP is being associated with a RADIUS account, this value will be ignored, as the data service is inherited from the RADIUS account.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

account_id Number

The ID of the account the IP is assigned to

service_id Number

The ID of the service the IP is associated with

non_inventoried_mac_address String

If this is a non-inventoried MAC, the MAC will be shown here, null otherwise.

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
   {
     "id": 1,
     "subnet_id": 1,
     "subnet": "192.168.100.5",
     "assigned_entity": "accounts",
     "assigned_id": 1,
     "ip_pool_id": null,
     "account_id": 1,
     "service_id": 4,
     "non_inventoried_mac_address": null,
     "description": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Account Inventory

Account_Inventory - Get all inventory items

Get a list of inventory on a specific account.

https://example.sonar.software/api/v1/accounts/:id/inventory_items

Parameter

Field Type Description
id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 1,
      "inventory_model_id": 1,
      "status": "lost",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:DD"
        },
        {
          "field_id": 2,
          "data": ""
        }
      ]
    },
    {
      "id": 2,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:0B"
        }
      ]
    },
    {
      "id": 29,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:DD:11:AA:BB:CC"
        },
        {
          "field_id": 2,
          "data": "1"
        }
      ]
    },
    {
      "id": 30,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:0A:BC:12"
        },
        {
          "field_id": 2,
          "data": "12345"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Inventory - Get individual inventory item

Get a specific inventory item on an account.

https://example.sonar.software/api/v1/accounts/:id/inventory_items/:item_id

Parameter

Field Type Description
id Number

The ID of the account

item_id Number

The ID of the inventory item

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 1,
    "status": "lost",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "00:00:00:00:00:DD"
      },
      {
        "field_id": 2,
        "data": ""
      }
    ]
  }
}

Account Invoices

Account_Invoices - Apply a deposit to an invoice

Apply a deposit to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the deposit has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_deposit/:deposit_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

deposit_id Number

The ID of the deposit

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Apply a deposit to an invoice

Apply a deposit to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the deposit has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_deposit/:deposit_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

deposit_id Number

The ID of the deposit

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Apply a discount to an invoice

Apply a discount to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the discount has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_discount/:discount_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

discount_id Number

The ID of the discount

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Apply a discount to an invoice

Apply a discount to an invoice. This will only work if the invoice has a remaining_due greater than 0 and the discount has an amount_remaining greater than 0.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/apply_discount/:discount_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

discount_id Number

The ID of the discount

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

debits Array

An array of debit IDs. These debits must be currently uninvoiced.

due_date Date

A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

debits Array

An array of debit IDs. These debits must be currently uninvoiced.

due_date optional Date

A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

message optional String

An optional message that will be printed on the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

message String

The optional invoice message

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "message": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

debits Array

An array of debit IDs. These debits must be currently uninvoiced

due_date Date

A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

date optional Date

The date the invoice is for. If this is ommitted, then the date will be set to today. Generally, you should omit this unless you have a reason to fix the invoice to a different date

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

debits Array

An array of debit IDs. These debits must be currently uninvoiced

due_date Date

A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

date optional Date

The date the invoice is for. If this is ommitted, then the date will be set to today. Generally, you should omit this unless you have a reason to fix the invoice to a different date

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Create invoice

Create an invoice from uninvoiced debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

debits Array

An array of debit IDs. These debits must be currently uninvoiced.

due_date Date

A due date in YYYY-MM-DD format. If this is omitted, the account 'due_days' parameter will be used to calculate a due date

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account. This is always null when you create an invoice, as auto pay is only run on auto invoices

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 202 OK
{
    "data":
    {
      "id": 312,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "15.32",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "Debit ID 12345 has already been invoiced."
         },
         "status_code": 422
     }
 }

Account_Invoices - Delete an invoice

Delete an invoice. Invoices can only be deleted in limited circumstances - they must be created manually (not an automatic, recurring invoice) and the invoice date must be after the last accounting period close date. Once an invoice is deleted, any credits applied, or debits included in the invoice, will be returned to the account.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
success Boolean

True if the invoice was deleted successfully.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot delete an invoice generated by the automatic billing process. Only manually created invoices can be deleted.",
     "status_code": 422
   }
 }

Account_Invoices - Freeze invoice

Freeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/freeze

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Freeze invoice

Freeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/freeze

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Get a base64 encoded invoice PDF

Get an invoice as a PDF, base64 encoded

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/pdf

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
invoice_id Number

The ID of the invoice

account_id Number

The ID of the account

base64 String

The base64 encoded invoice

HTTP/1.1 201 OK
{
  "data": {
    "invoice_id": 1,
    "account_id": 22,
    "base64": "JVBERi0xLjQK...."
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Invoices - Get a base64 encoded statement PDF

Get an invoice as a PDF, base64 encoded

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/pdf

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
invoice_id Number

The ID of the invoice

account_id Number

The ID of the account

base64 String

The base64 encoded statement

HTTP/1.1 201 OK
{
  "data": {
    "invoice_id": 1,
    "account_id": 22,
    "base64": "JVBERi0xLjQK...."
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Invoices - Get all account invoices

Get a list of the invoices for the account

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get all account invoices

Get a list of the invoices for the account

https://example.sonar.software/api/v1/accounts/:account_id/invoices

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice credits

Get an individual account invoice credits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/credits

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The ID of the credit

amount Number

The amount of the credit, in system currency

void Boolean

This will be true if the credit was reversed, or if the payment that created the credit is refunded or reversed

deposit_id Number

If this was created by a deposit (payment) then this will be the ID of the deposit

discount_id Number

If this was created by a discount, then this will be the ID of the discount

date Date

The date the credit was applied, in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 263,
      "amount": 60.50,
      "void": false,
      "deposit_id": 5,
      "discount_id": 0,
      "date": "2015-09-23 16:55:13"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice debits

Get an individual account invoice debits.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/debits

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 361,
      "amount": 34.34,
      "invoice_id": 366,
      "service_id": 22,
      "date": "2015-09-25 16:07:57",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 1,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Invoices - Get individual account invoice

Get an individual account invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Get individual account invoice

Get an individual account invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Link a child invoice to a master

Link a child invoice to a master. This generally does not need to be done manually, and is performed automatically by regular billing. Don't use this function unless you know exactly why you're using it!

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/link

Parameter

Field Type Description
account_id Integer

The ID of the account

invoice_id Integer

The ID of the master invoice

child_invoice_id Integer

The ID of the child invoice

Success 200

Field Type Description
id Integer

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Integer

The number of months of service this invoice was for

master_invoice_id Integer

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 12,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Reverse a credit

Reverse a credit on an invoice. You cannot reverse a credit if the accounting period is closed.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/credits/:credit_id/reverse

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

credit_id Number

The ID of the credit

Success 200

Field Type Description
id Number

The ID of the credit

amount Number

The amount of the credit, in system currency

void Boolean

This will be true if the credit was reversed, or if the payment that created the credit is refunded or reversed

deposit_id Number

If this was created by a deposit (payment) then this will be the ID of the deposit

discount_id Number

If this was created by a discount, then this will be the ID of the discount

date Date

The date the credit was applied, in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 263,
      "amount": 60.50,
      "void": false,
      "deposit_id": 5,
      "discount_id": 0,
      "date": "2015-09-23 16:55:13"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "debits": "The accounting period is closed."
         },
         "status_code": 422
     }
 }

Account_Invoices - Unfreeze invoice

Unfreeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/unfreeze

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

void Boolean

Whether or not the invoice has been voided.

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true,
      "void": false
    }
}

Account_Invoices - Unfreeze invoice

Unfreeze an invoice. This requires account super user permissions.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/unfreeze

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice

Success 200

Field Type Description
id Number

The internal ID of the invoice

date Date

The date the invoice is for

frozen Boolean

Whether or not the invoice is frozen

remaining_due Number

How much is remaining to be paid on the invoice

child_remaining_due Number

How much is remaining to be paid on any sub-account invoices linked to this one

number_of_months Number

The number of months of service this invoice was for

master_invoice_id Number

If this is an invoice on a sub account, this links to the master invoice that these charges roll up to

due_date Date

The date after which this invoice is past due

delinquent Boolean

Whether or not this invoice is delinquent

auto_pay Date

The date on which auto pay will be attempted, if the user has an auto pay method on their account

auto_pay_attempted Boolean

If this is true, auto pay has already been attempted. If not, it has not run yet

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 311,
      "date": "2015-09-23",
      "frozen": false,
      "remaining_due": "0.00",
      "child_remaining_due": "0.00",
      "number_of_months": 1,
      "master_invoice_id": 0,
      "due_date": "2015-10-03",
      "delinquent": false,
      "auto_pay": "2015-09-23",
      "auto_pay_attempted": true
    }
}

Account_Invoices - Void invoice

Void an invoice. Voiding an invoice removes any credits applied from payments or discounts, and reverses all debits on the invoice. The reversed debits will be used to pay off the invoice.

https://example.sonar.software/api/v1/accounts/:account_id/invoices/:invoice_id/void

Parameter

Field Type Description
account_id Number

The ID of the account

invoice_id Number

The ID of the invoice.

Success 200

Field Type Description
success Boolean

Will be true if the invoice was voided.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Invoice is already voided.",
     "status_code": 422
   }
 }

Account Payment Methods

Account_Payment_Methods - Create account payment method from an existing token

Create a new account payment method from an existing token. This should generally only be used when importing from another billing platform with existing tokens. You should ensure your Sonar system is already configured with the correct payment processor information before using this method. It is not possible for us to validate that the tokenized information is correct, so make sure you have done so on your side before submission.

https://example.sonar.software/api/v1/accounts/:account_id/tokenized_payment_method

Parameter

Field Type Description
account_id Number

The ID of the account this payment method should exist on

payment_processor_customer_profile_id optional String

If the payment processor being used stores a customer ID for their tokenization service, submit it here. This is optional, but must be included if the processor requires it

token String

The existing token for the payment method

name_on_account String

The name on the credit card, or the name on the bank account.

type String

The type of payment method

Allowed values: "credit card", "echeck"

identifier String

This is generally the last few digits of the credit card or bank account. This should be a maximum of 4 characters

expiration_year Number

Only required for credit cards, a 4 digit expiration year

expiration_month Number

Only required for credit cards, a 2 digit expiration month

auto Boolean

Whether or not this payment method should be set to auto pay

card_type String

If this is a credit card, the type of card this is

Allowed values: "visaelectron", "maestro", "forbrugsforeningen", "dankort", "visa", "mastercard", "amex", "dinersclub", "discover", "unionpay", "jcb"

line1 String

The address line of the credit card billing address. Only required if type is credit card.

city String

City of the credit card billing address. Only required if type is credit card.

state String

The state/province of the credit card billing address. Only required if type is credit card. You can obtain a valid list from _data/subdivisions/:country

zip String

ZIP/postal code of the credit card billing address. Only required if type is credit card.

country String

Two character ISO code of the country of the credit card billing address. Only required if type is credit card. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card, or the name on the bank account.

type String

The type of payment method.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method from an existing token

Create a new account payment method from an existing token. This should generally only be used when importing from another billing platform with existing tokens. You should ensure your Sonar system is already configured with the correct payment processor information before using this method. It is not possible for us to validate that the tokenized information is correct, so make sure you have done so on your side before submission.

https://example.sonar.software/api/v1/accounts/:account_id/tokenized_payment_method

Parameter

Field Type Description
account_id Number

The ID of the account this payment method should exist on

payment_processor_customer_profile_id optional String

If the payment processor being used stores a customer ID for their tokenization service, submit it here. This is optional, but must be included if the processor requires it

token String

The existing token for the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck"

identifier String

This is generally the last few digits of the credit card or bank account. This should be a maximum of 4 characters

expiration_year Number

Only required for credit cards, a 4 digit expiration year

expiration_month Number

Only required for credit cards, a 2 digit expiration month

auto Boolean

Whether or not this payment method should be set to auto pay

card_type String

If this is a credit card, the type of card this is

Allowed values: "visaelectron", "maestro", "forbrugsforeningen", "dankort", "visa", "mastercard", "amex", "dinersclub", "discover", "unionpay", "jcb"

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

Create a new account payment method. Be cautious when using this method as you will be transmitting raw credit card or bank account data. You must ensure you take all necessary precautions to secure this data and that you understand the impact this may have on your PCI compliance.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field Type Description
account_id Number

The ID of the account to add the payment method to

type String

The type of payment method being added

Allowed values: "credit card", "bank account"

expiration_month Number

An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts

expiration_year Number

A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account

account_number Number

For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number

cvc optional Number

The CVC/CVV code from the credit card. Optional but recommended for credit cards, should be excluded otherwise. Some providers require this - in this case, it is not optional.

routing_number Number

If this is a bank account, the routing number for the bank. Don't submit for credit cards

name_on_account String

The name that is on the credit card, or the name that is on the bank account

account_type String

If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards

Allowed values: "checking", "savings"

auto Boolean

Whether or not this payment method should be set to auto pay

line1 String

The address line of the credit card billing address. Only required if type is credit card.

city String

City of the credit card billing address. Only required if type is credit card.

state String

The state/province of the credit card billing address. Only required if type is credit card. You can obtain a valid list from _data/subdivisions/:country

zip String

ZIP/postal code of the credit card billing address. Only required if type is credit card.

country String

Two character ISO code of the country of the credit card billing address. Only required if type is credit card. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

Create a new account payment method. Be cautious when using this method as you will be transmitting raw credit card or bank account data. You must ensure you take all necessary precautions to secure this data and that you understand the impact this may have on your PCI compliance.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field Type Description
account_id Number

The ID of the account to add the payment method to

type String

The type of payment method being added

Allowed values: "credit card", "bank account"

expiration_month Number

An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts

expiration_year Number

A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account

account_number Number

For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number

routing_number Number

If this is a bank account, the routing number for the bank. Don't submit for credit cards

name_on_account String

The name that is on the credit card, or the name that is on the bank account

account_type String

If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards

Allowed values: "checking", "savings"

auto Boolean

Whether or not this payment method should be set to auto pay

line1 String

The address line of the credit card billing address. Only required if type is credit card.

city String

City of the credit card billing address. Only required if type is credit card.

state String

The state/province of the credit card billing address. Only required if type is credit card. You can obtain a valid list from _data/subdivisions/:country

zip String

ZIP/postal code of the credit card billing address. Only required if type is credit card.

country String

Two character ISO code of the country of the credit card billing address. Only required if type is credit card. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card, if this is a credit card payment method.

type String

The type of payment method.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

Create a new account payment method. Be cautious when using this method as you will be transmitting raw credit card or bank account data. You must ensure you take all necessary precautions to secure this data and that you understand the impact this may have on your PCI compliance.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field Type Description
account_id Number

The ID of the account to add the payment method to

type String

The type of payment method being added

Allowed values: "credit card", "bank account"

expiration_month Number

An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts

expiration_year Number

A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account

account_number Number

For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number

routing_number Number

If this is a bank account, the routing number for the bank. Don't submit for credit cards

name_on_account String

The name that is on the credit card, or the name that is on the bank account

account_type String

If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards

Allowed values: "checking", "savings"

auto Boolean

Whether or not this payment method should be set to auto pay

line1 String

The address line of the credit card billing address. Only required if type is credit card.

city String

City of the credit card billing address. Only required if type is credit card.

state String

The state/province of the credit card billing address. Only required if type is credit card. You can obtain a valid list from _data/subdivisions/:country

zip String

ZIP/postal code of the credit card billing address. Only required if type is credit card.

country String

Two character ISO code of the country of the credit card billing address. Only required if type is credit card. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Create account payment method

Create a new account payment method. Be cautious when using this method as you will be transmitting raw credit card or bank account data. You must ensure you take all necessary precautions to secure this data and that you understand the impact this may have on your PCI compliance.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field Type Description
account_id Number

The ID of the account to add the payment method to

type String

The type of payment method being added

Allowed values: "credit card", "bank account"

expiration_month Number

An integer representing the expiration month, if this is a credit card. 1 for January, 12 for December. Don't submit for bank accounts

expiration_year Number

A four digit integer representing the expiration year, if this is a credit card. Don't submit for bank account

account_number Number

For credit cards, this is the account number on the card, typically 16 digits but can be a different length. For bank accounts, this is the bank account number

routing_number Number

If this is a bank account, the routing number for the bank. Don't submit for credit cards

name_on_account String

The name that is on the credit card, or the name that is on the bank account

account_type String

If this is a bank account, submit one of 'checking' or 'savings'. Don't submit for credit cards

Allowed values: "checking", "savings"

auto Boolean

Whether or not this payment method should be set to auto pay

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 201 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The selected type is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Delete account payment method

Delete an account payment method

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id Number

The ID of the payment method

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the payment method could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Payment_Methods - Get all account payment methods

Get a list of the payment methods for account

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card, or the name on the bank account.

type String

The type of payment method.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Payment_Methods - Get all account payment methods

Get a list of the payment methods for account

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 111,
      "type": "credit card",
      "identifier": "2333",
      "expiration_month": 8,
      "expiration_year": 2020,
      "auto": true
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Payment_Methods - Get individual account payment method

Get an individual account payment method.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id Number

The ID of the payment method

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card, or the name on the bank account

type String

The type of payment method.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 200 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Account_Payment_Methods - Get individual account payment method

Get an individual account payment method.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id Number

The ID of the payment method

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 200 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Account_Payment_Methods - Toggle the auto payment setting

Toggle the automatic payment flag on a payment method. Only one payment method can be auto at a time - enabling auto on a method will disable auto on all other methods.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:id/toggle_auto

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the payment method

auto Boolean

The automatic payment state of the payment method

Default value: false

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card, or the name on the bank account.

type String

The type of payment method.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 201 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "auto must be a boolean.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Update stored credit card

Update a stored credit card on an account.

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field Type Description
account_id Number

The ID of the account to update the address on

payment_method_id Number

The ID of the payment method

name_on_account String

The name on the credit card.

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December.

expiration_year Number

A 4 digit integer representing the expiration year for credit cards.

auto Boolean

Whether or not this should be an automatic payment method. Setting auto to true on a payment method will unset auto on any other payment methods on the account

line1 String

The address line of the credit card billing address.

city String

City of the credit card billing address.

state String

The state/province of the credit card billing address.. You can obtain a valid list from _data/subdivisions/:country

zip String

ZIP/postal code of the credit card billing address..

country String

Two character ISO code of the country of the credit card billing address.. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment method

name_on_account String

The name on the credit card

type String

The type of payment method, will always be credit card.

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

line1 string

Line 1 of the credit card billing address.

city string

The city of the credit card billing address.

state string

The state/province of the credit card billing address.

zip string

ZIP/postal code of the credit card billing address.

country string

Two character ISO country code of the credit card billing address.

HTTP/1.1 200 OK
{
  "data": {
     "id": 1195,
     "name_on_account": "Steve Martin",
     "type": "credit card",
     "identifier": "1111",
     "expiration_month": "09",
     "expiration_year": 2018,
     "auto": false,
     "line1": "4546 N Avenue",
     "city": "Somewhere",
     "state": "WI",
     "zip": "51234",
     "country": "US"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "The selected value is not valid.",
         },
         "status_code": 422
     }
 }

Account_Payment_Methods - Update account payment method

Update an account payment method. Currently, the only thing that can be changed is whether or not the payment method is an auto-pay method. If you need to modify a payment method, delete the existing one and create a new one

https://example.sonar.software/api/v1/accounts/:account_id/payment_methods/:payment_method_id

Parameter

Field Type Description
account_id Number

The ID of the account to update the address on

payment_method_id Number

The ID of the payment method

auto Boolean

Whether or not this should be an automatic payment method. Setting auto on a payment method will unset auto on any other payment methods on the account

Success 200

Field Type Description
id Number

The ID of the payment method

type String

The type of payment method

Allowed values: "credit card", "echeck", "ach"

identifier String

Some method of identifying the account. For credit cards, the last 4 digits of the account number. For bank accounts, some quantity of digits

expiration_month Number

A representation of the expiration month for credit cards as an integer, where 1 is January and 12 is December

expiration_year Number

A 4 digit integer representing the expiration year for credit cards

auto Boolean

Whether or not this is an auto-pay method. Only one method can be set to auto-pay on an account

HTTP/1.1 200 OK
{
  "data": {
    "id": 111,
    "type": "credit card",
    "identifier": "2333",
    "expiration_month": 8,
    "expiration_year": 2020,
    "auto": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "auto": "The selected value is not valid.",
         },
         "status_code": 422
     }
 }

Account Services

Account_Services - Add a package to an account

Add a package to an account. A package is a group of recurring and/or expiring services. This will return a random, unique ID. This ID can be used to delete the package later. This unique ID is used to allow the account to have multiple instances of the same package, but still differentiate between them.

https://example.sonar.software/api/v1/accounts/:account_id/packages

Parameter

Field Type Description
account_id Number

The ID of the account to add the package to

package_id Number

The ID of the package you wish to add

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field Type Description
unique_package_id Boolean

This unique ID will be attached to all services on the account list that are part of this specific package. You need this ID to remove the package later.

HTTP/1.1 201 OK
{
    "data": {
        "unique_package_id": "5787b0cc6b25f"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Add a package to an account

Add a package to an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages

Parameter

Field Type Description
account_id Number

The ID of the account to add the package to

package_id Number

The ID of the package you wish to add

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field Type Description
success Boolean

If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

description optional String

If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!

quantity optional Number

If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing.

Default value: 1

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

amount optional Number

This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.

price_override optional Number

The amount to price override the service to. Only valid for recurring/expiring services.

price_override_reason optional String

The reason for applying the price override. Only valid for recurring/expiring services.

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

next_bill_date optional Date

The next date this service will bill. Only valid for multi-month services. If unset, it will bill on the next account billing date.

service_metadata optional Array

An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field Type Description
unique_service_relationship_id Number

The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}
HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

description optional String

If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!

quantity optional Number

If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing.

Default value: 1

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

amount optional Number

This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.

price_override optional Number

The amount to price override the service to. Only valid for recurring/expiring services.

price_override_reason optional String

The reason for applying the price override. Only valid for recurring/expiring services.

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

service_metadata optional Array

An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field Type Description
unique_service_relationship_id Number

The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}
HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

description optional String

If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!

quantity optional Number

If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. If this is for a recurring service, the service will be added with this quantity for prorating, and future billing.

Default value: 1

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

amount optional Number

This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.

price_override optional Number

The amount to price override the service to. Only valid for recurring/expiring services.

price_override_reason optional String

The reason for applying the price override. Only valid for recurring/expiring services.

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field Type Description
unique_service_relationship_id Number

The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}
HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

description optional String

If you are entering a one time charge/adjustment, you can enter a description here to override the service name. This will show up on customer invoices!

quantity optional Number

If you are submitting a one time service, this is the quantity to add. If the one time service is $50, and this value is '3', a single transaction will be created for $150. Ignored for any non-one time services.

Default value: 1

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

amount optional Number

This is only valid for adjustment services, and is required if you are submitting one. This is the amount you wish to adjust the account by.

price_override optional Number

The amount to price override the service to. Only valid for recurring/expiring services.

price_override_reason optional String

The reason for applying the price override. Only valid for recurring/expiring services.

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field Type Description
unique_service_relationship_id Number

The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}
HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

amount Number

This is only valid for adjustment services. This is the amount you wish to adjust the account by.

price_override optional Number

The amount to price override the service to. Only valid for recurring/expiring services.

price_override_reason optional String

The reason for applying the price override. Only valid for recurring/expiring services.

Success 200

Field Type Description
unique_service_relationship_id Number

The unique ID representing the relationship of this specific service to this account. This is used in updates and deletes. If you are not adding a stored service (e.g. if you are performing a one time transaction/adjustment) this will instead return 'success': true on success.

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}
HTTP/1.1 201 OK
{
    "data": {
        "unique_service_relationship_id": 3
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Add a service to an account

Add a service to an account. Adding a recurring or expiring service will add it to the account for future billing. Adding an adjustment or one time service will create a transaction for that service

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account to add the address to

service_id Number

The ID of the service you wish to add

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

amount Number

This is only valid for adjustment services. This is the amount you wish to adjust the account by

Success 200

Field Type Description
success Boolean

If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "You do not have permission to apply adjustment services.",
         "status_code": 422
     }
 }

Account_Services - Delete a package from an account

Delete a package from an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages/:unique_package_id

Parameter

Field Type Description
account_id Number

The ID of the account to delete the package from

unique_package_id Number

The unique ID returned when the package was added.

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field Type Description
success Boolean

If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Delete a package from an account

Delete a package from an account. A package is a group of recurring and/or expiring services

https://example.sonar.software/api/v1/accounts/:account_id/packages/:package_id

Parameter

Field Type Description
account_id Number

The ID of the account to delete the package from

package_id Number

The ID of the package you wish to delete

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field Type Description
success Boolean

If this is true, the process was completed successfully. If there are any errors, you will receive a non-2xx HTTP response code and an error object

HTTP/1.1 201 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 422
 {
     "error": {
         "message": "One of the services in the package is inactive.",
         "status_code": 422
     }
 }

Account_Services - Delete account service

Delete a service from an account. Only valid for recurring/expiring services

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service

prorate Boolean

Whether or not you want to prorate this transaction, only valid for recurring services. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used. If you do have account superuser, you must input a value here if you do not want the default of 'false'

Default value: false

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the service could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

next_bill_date Date

The next date this service will bill. If null, it will bill on the next account billing date.

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "next_bill_date": "2018-11-06",
      "metadata": {}
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "next_bill_date": "2018-11-06",
      "metadata": {
           "12": "test"
      }
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "metadata": {}
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "metadata": {
           "12": "test"
      }
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

service_id Integer

The ID of the service

account_id Integer

The ID of the account

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1,
      "service_id": 4,
      "account_id": 3
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12,
      "service_id": 1,
      "account_id": 6
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null,
      "quantity": 1
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com",
      "quantity": 12
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 8,
      "name_override": null
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_package_id": null,
      "unique_service_relationship_id": 10,
      "name_override": "Hosting for www.example.com"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get all account services

Get a list of the recurring and expiring services on the account.

https://example.sonar.software/api/v1/accounts/:account_id/services

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_service_relationship_id": 8
    },
    {
      "id": 7,
      "number_of_times_billed": 0,
      "price_override": null,
      "price_override_reason": null,
      "package_id": null,
      "unique_service_relationship_id": 10
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

next_bill_date Date

The next date this service will bill. If null, it will bill on the next account billing date.

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "next_bill_date": null,
    "metadata": {
         "12": "test"
    }
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "metadata": {
         "12": "test"
    }
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

service_id Integer

The ID of the service

account_id Integer

The ID of the account

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5,
    "service_id": 5,
    "account_id": 1
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity Integer

The quantity of this particular service instance

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "quantity": 5
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Account_Services - Get individual account service

Get details on an individual account service.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

Success 200

Field Type Description
unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "number_of_times_billed": 0,
    "price_override": null,
    "price_override_reason": null,
    "package_id": null,
    "unique_service_relationship_id": 10
  }
}

Account_Services - Get usage based billing policy details

Get details on any usage based billing policy that may be applied to the customer account, along with some other useful details.

https://example.sonar.software/api/v1/accounts/:id/usage_based_billing_policy_details

Parameter

Field Type Description
id Number

The internal ID of the account

Success 200

Field Type Description
has_policy Boolean

Does the account have a usage based billing policy being applied to it?

policy_cap_in_gigabytes Number

The cap on the policy in gigabytes. This does not include any rollover or top offs.

rollover_enabled Boolean

Is the rollover feature enabled on this policy?

rollover_expiration_enabled Boolean

Does rollover data expire?

rollover_expires_after_months Number

If rollover_expiration is true, this is the number of months after which rollover data expires.

assess_charges_at_end_of_billing_period Boolean

If this is true, the customer will be charged for overages at the end of the billing period based on the values in overage_cost and overage_units_in_gigabytes.

allow_user_to_purchase_capacity Boolean

If this is true, the customer can purchase additional capacity during his billing cycle based on the values in overage_cost and overage_units_in_gigabytes.

overage_cost Number

The cost of overages on this policy.

overage_units_in_gigabytes Number

This is the amount of data provided for the cost defined in overage_cost. E.g. if this is 5 and overage_cost is 10, then $10 provides 5 gigabytes.

rollover_available_in_bytes Number

If rollover_enabled is true, then this is the amount of additional data available in the current billing period.

purchased_top_off_total_in_bytes Number

If allow_user_to_purchase_capacity is true, then this is the amount of additional data purchased in the current billing period.

HTTP/1.1 200 OK
{
  "data": {
    "has_policy": true,
    "policy_cap_in_gigabytes": 1,
    "rollover_enabled": true,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "overage_cost": null,
    "overage_units_in_gigabytes": null,
    "rollover_available_in_bytes": 10000000000,
    "purchased_top_off_total_in_bytes": 0
  }
}

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override optional Number

The amount to price override the service by

price_override_reason optional String

The reason for applying the price override

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity optional Integer

If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

next_bill_date optional Date

The next date this service will bill. Only valid for multi-month services. If unset, it will bill on the next account billing date.

service_metadata optional Array

An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

next_bill_date Date

The next date this service will bill. If null, it will bill on the next account billing date.

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "next_bill_date": null,
    "metadata": {
       "1": "test!!!123!",
       "2": "another test",
       "3": null
    }
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override optional Number

The amount to price override the service by

price_override_reason optional String

The reason for applying the price override

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity optional Integer

If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

service_metadata optional Array

An array of objects, each object should have an 'id' and 'value' property, where the 'id' is the ID of a service metadata field, and the 'value' is the value you wish to set the field to.

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

metadata Object

An object where the property is the metadata ID, and the value is the metadata value.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "metadata": {
       "1": "test!!!123!",
       "2": "another test",
       "3": null
    }
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override optional Number

The amount to price override the service by

price_override_reason optional String

The reason for applying the price override

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity optional Integer

If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

service_id Integer

The ID of the service

account_id Integer

The ID of the account

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null,
    "service_id": 4,
    "account_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override optional Number

The amount to price override the service by

price_override_reason optional String

The reason for applying the price override

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

quantity optional Integer

If this is set, the quantity of the service will be adjusted to this amount. Must be 1 or greater.

prorate optional Boolean

Whether or not you want to prorate this transaction, only valid if you are changing the quantity. If you don't have account super user permission, anything submitted here will be ignored and the system global prorate value will be used.

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override, price override reason, and name override. To remove a price override or name override, set the price_override property to null.

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override optional Number

The amount to price override the service by

price_override_reason optional String

The reason for applying the price override

name_override optional String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_package_id String

If this service is part of a package, this is a unique string that will identify all services added within the same package. The function of this string is to differentiate one package from another, if the same package is added to the account twice.

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

name_override String

If this is set, then any transactions generated from this service when automatic billing runs will have this set as their description. See the debits/discounts endpoints for more details.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_package_id": null,
    "unique_service_relationship_id": 10,
    "name_override": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account_Services - Update account service

Update an account service. The only values that can be changed are the price override and price override reason. To remove a price override, set the price_override property to null

https://example.sonar.software/api/v1/accounts/:account_id/services/:unique_service_relationship_id

Parameter

Field Type Description
account_id Number

The ID of the account

unique_service_relationship_id Number

The unique relationship ID of the service that already exists on the account

price_override Number

The amount to price override the service by

price_override_reason String

The reason for applying the price override

Success 200

Field Type Description
id Number

The internal ID of the service. You can use this to retrieve service details from the /services endpoint

number_of_times_billed Number

Only valid for expiring services, this is the number of times the service has been run

price_override Number

If the service has a price override on it, it will be represented here. Otherwise, this will be null

price_override_reason String

If the service has a price override, the optional reason will be displayed here

package_id Number

If this service was added as part of a package, the ID of the package will be displayed here. Services added as part of a package cannot be removed, except by removing the package itself

unique_service_relationship_id Number

This is a unique ID that represents this specific service as it relates to this specific account. This ID is used when adding a price override for this service, or deleting this service from the account

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "number_of_times_billed": 2,
    "price_override": "12.50",
    "price_override_reason": "Discounting service",
    "package_id": null,
    "unique_service_relationship_id": 10
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique_service_relationship_id": "The selected unique_service_relationship_id is not valid.",
         },
         "status_code": 422
     }
 }

Account Tax Overrides

Account_Tax_Overrides - Create a new account tax override

Create a new account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides

Parameter

Field Type Description
account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success 200

Field Type Description
id Integer

The tax override ID

account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "tax_id": "The tax ID is invalid."
     },
     "status_code": 422
   }
 }

Account_Tax_Overrides - Delete an account tax override

Delete an account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the account tax override

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account tax override could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "account tax override does not exist.",
         "status_code": 404
     }
 }

Account_Tax_Overrides - Get all account tax overrides

Get all account tax overrides. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

account_id Integer

The ID of the account

Success 200

Field Type Description
id Integer

The tax override ID

account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "tax_id": 3,
      "account_id": 12,
      "rate": 15.43234
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Tax_Overrides - Get an individual account tax override

Get an individual account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the account tax override

Success 200

Field Type Description
id Integer

The tax override ID

account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account_Tax_Overrides - Update account tax override

Update an existing account tax override. This requires account super user permission.

https://example.sonar.software/api/v1/accounts/:account_id/account_tax_overrides/:id

Parameter

Field Type Description
id Integer

The ID of the tax override

account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

Success 200

Field Type Description
id Integer

The tax override ID

account_id Integer

The account ID

tax_id Integer

The ID of the tax to override

rate Number

The rate at which to override. If this is a flat tax, this is a monetary amount. If this is a percentage based tax, this will be the percentage to override to.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "tax_id": 3,
    "account_id": 12,
    "rate": 15.43234
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Account Transactions

Account_Transactions - Apply an external PayPal payment

Store an externally made PayPal payment into Sonar. This should only be used to store PayPal payments made using the same PayPal API credentials as you have entered in Sonar. This endpoint is mostly designed to implement things like an external customer portal.

https://example.sonar.software/api/v1/accounts/:id/transactions/paypal_payments

Parameter

Field Type Description
id Number

The ID of the account

amount Number

The amount of the successful PayPal payment

transaction_id String

The transaction ID of the PayPal payment. This is the sale ID provided in the returned transaction list from PayPal. It is important this is correct, or attempts to refund inside Sonar will fail.

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "paypal"

response_message String

Will be 'APPROVED'

success Boolean

Will always be true in this scenario

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 12.53,
    "payment_method_id": 0,
    "type": "paypal",
    "response_message": "APPROVED",
    "transaction_id": "ABC123",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2016-06-01 18:23:02"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "PayPal processing is not enabled.",
     "status_code": 422
   }
 }

Account_Transactions - Create payment

Create a payment. If you submit a payment method ID, this will use the payment processor for the payment method to run the payment in real time. If you do not, it will add a payment via whatever method you specify.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id optional Number

The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified

payment_method optional String

A string representing the type of payment this is. If payment_method_id is included, this is ignored

Allowed values: "cash", "check", "wire"

reference optional String

If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.

amount Number

The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)

auto_apply Boolean

Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance

Default value: true

date optional Date

The date the payment should be applied for. Cannot be in the future, and is ignored for payments made via a payment method. If null, the current date will be used.

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Create payment

Create a payment. If you submit a payment method ID, this will use the payment processor for the payment method to run the payment in real time. If you do not, it will add a payment via whatever method you specify.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id optional Number

The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified

payment_method optional String

A string representing the type of payment this is. If payment_method_id is included, this is ignored

Allowed values: "cash", "check", "wire"

reference optional String

If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.

amount Number

The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)

auto_apply Boolean

Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance

Default value: true

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Create payment

Create a payment. If you submit a payment method ID, this will use the payment processor for the payment method to run the payment in real time. If you do not, it will add a payment via whatever method you specify.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field Type Description
account_id Number

The ID of the account

payment_method_id optional Number

The ID of the payment method to use to make the payment. If this is omitted, payment_method must be specified

payment_method optional String

A string representing the type of payment this is. If payment_method_id is included, this is ignored

Allowed values: "cash", "check", "wire"

reference optional String

If you're submitting a cash, check or wire payment, you can submit a string here that will be stored as a reference. If you're using a payment_method_id, this will be ignored, as the message stored will be the response from the payment processor.

amount Number

The amount of the payment to post. This should be a decimal in the format xx.yy (e.g. 10.32 or 134.23)

auto_apply Boolean

Whether or not to automatically apply this payment to any outstanding invoices. If this is false, you will need to manually apply this payment to invoices to reduce their due balance

Default value: true

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Edit account payment

Edit a payment. You can only change the reference on a wire, cash, check, or other payment.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:id

Parameter

Field Type Description
account_id Number

The ID of the account

id Number

The ID of the payment

response_message optional String

The reference you want to store for this payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

If this payment is refunded/reversed, this will be true

reversed_at Date

If a payment is refunded/reversed, this will be the date the reversal occurs

date Date

The date the payment was applied

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "amount": 1,
    "payment_method_id": null,
    "type": "check",
    "response_message": "test",
    "transaction_id": null,
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2016-07-10 18:43:28"
  }
}

Account_Transactions - Edit debit description

Edit the description on a debit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field Type Description
account_id Number

The ID of the account

debit_id Number

The ID of the debit

description optional String

The description to overwrite the existing description with. Send null to remove it and revert to the service name.

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Fast Internet",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Edit discount description

Edit the description on a discount

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field Type Description
account_id Number

The ID of the account

discount_id Number

The ID of the discount

description optional String

The description to overwrite the existing description with. Send null to revert back to the service name.

Success 200

Field Type Description
id Number

An ID representing the individual discount

amount Number

The amount of the discount in the system currency

amount_remaining Number

How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount

service_id Number

The ID of the service that the discount is associated with

date Date

The date and time the discount was created in UTC

reversed Boolean

If this is true, the discount has been reversed

reversed_at Date

If reversed is true, this is the date the discount was reversed

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Service name",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get all account debits

Get a list of the debits on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 200,
      "amount": 186.48,
      "invoice_id": 241,
      "service_id": 6,
      "date": "2015-09-17 01:48:46",
      "reversed": true,
      "reversed_at": "2015-09-22",
      "discount_id": 265,
      "number_of_months": 3,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Some Other Tax",
          "amount": 3
        }
      ],
      "description": "Some Service",
      "quantity": 1
    },
    {
      "id": 201,
      "amount": 181.50,
      "invoice_id": 241,
      "service_id": 7,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 3,
      "taxes": [],
      "description": "Look ma, no hands!",
      "quantity": 3,
      "general_ledger_code": "1000",
      "general_ledger_code_description": "test test"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account debits

Get a list of the debits on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 200,
      "amount": 186.48,
      "invoice_id": 241,
      "service_id": 6,
      "date": "2015-09-17 01:48:46",
      "reversed": true,
      "reversed_at": "2015-09-22",
      "discount_id": 265,
      "number_of_months": 3,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Some Other Tax",
          "amount": 3
        }
      ]
    },
    {
      "id": 201,
      "amount": 181.50,
      "invoice_id": 241,
      "service_id": 7,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "discount_id": null,
      "number_of_months": 3,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account deposits

Get a list of the deposits on the account. A deposit is created by a payment being applied to an account. The payment itself is tracked separately and is available at the /payments endpoint

https://example.sonar.software/api/v1/accounts/:account_id/transactions/deposits

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual deposit

amount Number

The amount of the deposit in the system currency

amount_remaining Number

How much of the deposit has not been applied as credits on invoices

payment_id Number

The ID of the payment that the deposit was created by

void Boolean

If a payment is reversed, the deposit will be void

date Date

The date and time the discount was created in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "amount_remaining": 0.00,
      "payment_id": 3,
      "void": false,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account discounts

Get a list of the discounts on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual discount

amount Number

The amount of the discount in the system currency

amount_remaining Number

How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount

service_id Number

The ID of the service that the discount is associated with

date Date

The date and time the discount was created in UTC

reversed Boolean

If this is true, the discount has been reversed

reversed_at Date

If reversed is true, this is the date the discount was reversed

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 265,
      "amount": 186.48,
      "amount_remaining": "198.48",
      "service_id": 6,
      "date": "2015-09-22 03:03:17",
      "reversed": false,
      "reversed_at": null,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Other Tax",
          "amount": 3
        }
      ],
      "description": "Some description",
      "quantity": 1,
      "general_ledger_code": null,
      "general_ledger_code_description": null
    },
    {
      "id": 227,
      "amount": 214.53,
      "amount_remaining": 0.00,
      "service_id": 2,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    },
    {
      "id": 228,
      "amount": 167.43,
      "amount_remaining": 1.98,
      "service_id": 10,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": [],
      "description": "Installation Credit",
      "quantity": 1,
      "general_ledger_code": null,
      "general_ledger_code_description": null
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account discounts

Get a list of the discounts on the account.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual discount

amount Number

The amount of the discount in the system currency

amount_remaining Number

How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount

service_id Number

The ID of the service that the discount is associated with

date Date

The date and time the discount was created in UTC

reversed Boolean

If this is true, the discount has been reversed

reversed_at Date

If reversed is true, this is the date the discount was reversed

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 265,
      "amount": 186.48,
      "amount_remaining": "198.48",
      "service_id": 6,
      "date": "2015-09-22 03:03:17",
      "reversed": false,
      "reversed_at": null,
      "taxes": [
        {
          "description": "Sales Tax",
          "amount": 9
        },
        {
          "description": "Other Tax",
          "amount": 3
        }
      ]
    },
    {
      "id": 227,
      "amount": 214.53,
      "amount_remaining": 0.00,
      "service_id": 2,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    },
    {
      "id": 228,
      "amount": 167.43,
      "amount_remaining": 1.98,
      "service_id": 10,
      "date": "2015-09-17 01:48:46",
      "reversed": false,
      "reversed_at": null,
      "taxes": []
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account payments

Get a list of the payments on the account. A payment creates a deposit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

If this payment is refunded/reversed, this will be true

reversed_at Date

If a payment is refunded/reversed, this will be the date the reversal occurs

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "payment_method_id": 111,
      "type": "credit card",
      "response_message": "Successful.",
      "transaction_id": "12345ABC",
      "success": true,
      "reversed": false,
      "reversed_at": null,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get all account payments

Get a list of the payments on the account. A payment creates a deposit

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments

Parameter

Field Type Description
account_id Number

The ID of the account

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

If this payment is refunded/reversed, this will be true

reversed_at Date

If a payment is refunded/reversed, this will be the date the reversal occurs

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "amount": 55.39,
      "payment_method_id": 111,
      "type": "credit card",
      "response_message": "Successful.",
      "success": true,
      "reversed": false,
      "reversed_at": null,
      "date": "2015-09-23 16:55:12"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Account_Transactions - Get individual account debit

Get an individual account debit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field Type Description
account_id Number

The ID of the account

debit_id Number

The ID of the debit

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "Some service name",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get individual account debit

Get an individual account debit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/debits/:debit_id

Parameter

Field Type Description
account_id Number

The ID of the account

debit_id Number

The ID of the debit

Success 200

Field Type Description
id Number

An ID representing the individual debit

amount Number

The amount of the debit in the system currency

invoice_id Number

The invoice the debit is associated with, if it is associated with an invoice. Null otherwise

service_id Number

The ID of the service that the debit is associated with

date Date

The date and time the debit was created in UTC

reversed Boolean

If this is true, the debit has been reversed

reversed_at Date

If reversed is true, this is the date the debit was reversed

discount_id Number

If reversed is true, this is the ID of the discount that was created to reverse the debit

number_of_months Number

If this account is billed in multi-month increments, this is the number of months of service that this single debit represents. You can divide amount by this value to get the amount that is for each month of service

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged

HTTP/1.1 200 OK
{
  "data": {
    "id": 200,
    "amount": 186.48,
    "invoice_id": 241,
    "service_id": 6,
    "date": "2015-09-17 01:48:46",
    "reversed": true,
    "reversed_at": "2015-09-22",
    "discount_id": 265,
    "number_of_months": 3,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ]
  }
}

Account_Transactions - Get individual account deposit

Get an individual account deposit by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/deposits/:deposit_id

Parameter

Field Type Description
account_id Number

The ID of the account

deposit_id Number

The ID of the deposit

Success 200

Field Type Description
id Number

An ID representing the individual deposit

amount Number

The amount of the deposit in the system currency

amount_remaining Number

How much of the deposit has not been applied as credits on invoices

payment_id Number

The ID of the payment that the deposit was created by

void Boolean

If a payment is reversed, the deposit will be void

date Date

The date and time the discount was created in UTC

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "amount_remaining": 0.00,
    "payment_id": 3,
    "void": false,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Get individual account discount

Get an individual account discount by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field Type Description
account_id Number

The ID of the account

discount_id Number

The ID of the discount

Success 200

Field Type Description
id Number

An ID representing the individual discount

amount Number

The amount of the discount in the system currency

amount_remaining Number

How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount

service_id Number

The ID of the service that the discount is associated with

date Date

The date and time the discount was created in UTC

reversed Boolean

If this is true, the discount has been reversed

reversed_at Date

If reversed is true, this is the date the discount was reversed

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

description String

A description for the transaction, if one was set. The name of the service that generated it, otherwise.

quantity Number

If this was a one time transaction, this is the number of applications that created this single transaction.

Default value: 1

general_ledger_code String

The general ledger code for this transaction

general_ledger_code_description String

The description for the general ledger code for this transaction

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ],
    "description": "I wrote this",
    "quantity": 1,
    "general_ledger_code": "1000",
    "general_ledger_code_description": "test test"
  }
}

Account_Transactions - Get individual account discount

Get an individual account discount by ID

https://example.sonar.software/api/v1/accounts/:account_id/transactions/discounts/:discount_id

Parameter

Field Type Description
account_id Number

The ID of the account

discount_id Number

The ID of the discount

Success 200

Field Type Description
id Number

An ID representing the individual discount

amount Number

The amount of the discount in the system currency

amount_remaining Number

How much of the discount has not been applied as credits on invoices. This includes any tax credits, whereas the amount value is the raw amount of the discount, so it is possible on reversals for the amount_remaining to be more than the amount

service_id Number

The ID of the service that the discount is associated with

date Date

The date and time the discount was created in UTC

reversed Boolean

If this is true, the discount has been reversed

reversed_at Date

If reversed is true, this is the date the discount was reversed

taxes Array

An array of taxes that are charged. The array contains multiple objects, each object has two parameters - description and amount, which represent a textual description of the tax and the amount charged. Taxes will only ever exist on a discount if the discount was created by reversing a debit - the taxes will be the tax credit assessed for any taxes charged on the debit

HTTP/1.1 200 OK
{
  "data": {
    "id": 265,
    "amount": 186.48,
    "amount_remaining": 198.48,
    "service_id": 6,
    "date": "2015-09-22 03:03:17",
    "reversed": false,
    "reversed_at": null,
    "taxes": [
      {
        "description": "Sales Tax",
        "amount": 9
      },
      {
        "description": "Other Tax",
        "amount": 3
      }
    ]
  }
}

Account_Transactions - Get individual account payment

Get an individual payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

If this payment is refunded/reversed, this will be true

reversed_at Date

If a payment is refunded/reversed, this will be the date the reversal occurs

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Get individual account payment

Get an individual payment

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

If this payment is refunded/reversed, this will be true

reversed_at Date

If a payment is refunded/reversed, this will be the date the reversal occurs

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": false,
    "reversed_at": null,
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field Type Description
id Number

The ID of the account

number Number

The credit card number

cvc optional Number

The CVC/CVV code on the credit card. Some providers require that this is sent - if so, this is not optional.

expiration_month Number

The month as a digit (1-12)

expiration_year Number

The 4 digit expiration year (e.g. 2018)

amount Number

The amount to charge the card

name_on_account String

The name on the credit card

line1 String

Line 1 of the card address (e.g. the street address.)

city String

The city of the card address

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

zip String

The ZIP/postal code of the card address

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment

transaction_id String

The transaction ID from the payment processor

message String

The message from the payment processor

success Boolean

Whether or not the payment was successfully processed

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field Type Description
id Number

The ID of the account

number Number

The credit card number

expiration_month Number

The month as a digit (1-12)

expiration_year Number

The 4 digit expiration year (e.g. 2018)

amount Number

The amount to charge the card

name_on_account String

The name on the credit card

line1 String

Line 1 of the card address (e.g. the street address.)

city String

The city of the card address

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

zip String

The ZIP/postal code of the card address

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

Success 200

Field Type Description
id Number

The ID of the payment

transaction_id String

The transaction ID from the payment processor

message String

The message from the payment processor

success Boolean

Whether or not the payment was successfully processed

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Make a one time credit card payment

Make a one time credit card payment. This does not save the credit card to Sonar.

https://example.sonar.software/api/v1/accounts/:id/transactions/one_time_credit_card_payment

Parameter

Field Type Description
id Number

The ID of the account

number Number

The credit card number

expiration_month Number

The month as a digit (1-12)

expiration_year Number

The 4 digit expiration year (e.g. 2018)

amount Number

The amount to charge the card

Success 200

Field Type Description
id Number

The ID of the payment

transaction_id String

The transaction ID from the payment processor

message String

The message from the payment processor

success Boolean

Whether or not the payment was successfully processed

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "transaction_id": "100325923924",
    "message": "Declined Sale",
    "success": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "That is not a valid credit card number. Please check and try again.",
     "status_code": 422
   }
 }

Account_Transactions - Refund a payment

Refund a payment. This will refund the payment transaction. You can only refund payments that are made with a payment processor, or via ACH batch. Cash, check or wire payments can only be reversed, as we have no way of refunding those payments.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/refund

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Refund a payment

Refund a payment. This will refund the payment transaction. You can only refund payments that are made with a payment processor, or via ACH batch. Cash, check or wire payments can only be reversed, as we have no way of refunding those payments.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/refund

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Reverse a payment

Reverse a payment. This will reverse the payment transaction but will not issue a refund to the payment processor. Once a payment is reversed, it cannot be refunded, so ensure you use refund instead of reverse if you want the payment processor to issue a refund.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/reverse

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

transaction_id String

The transaction ID from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "transaction_id": "12345ABC",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Account_Transactions - Reverse a payment

Reverse a payment. This will reverse the payment transaction but will not issue a refund to the payment processor. Once a payment is reversed, it cannot be refunded, so ensure you use refund instead of reverse if you want the payment processor to issue a refund.

https://example.sonar.software/api/v1/accounts/:account_id/transactions/payments/:payment_id/reverse

Parameter

Field Type Description
account_id Number

The ID of the account

payment_id Number

The ID of the payment

Success 200

Field Type Description
id Number

An ID representing the individual payment

amount Number

The amount of the deposit in the system currency

payment_method_id Number

The ID of the payment method used to make the payment. If this was a payment made using an unstored payment method (e.g. paper check, cash or wire) this will be null

type String

The type of payment this is

Allowed values: "credit card", "echeck", "ach", "cash", "check", "wire", "paypal"

response_message String

The response message from the payment processor, if one was used for this transaction

success Boolean

Whether or not this payment was successful. Will only ever show false if this was run through a payment processor

reversed Boolean

This will be true if the payment reversed successfully

reversed_at Date

This will be the current date if the payment was reversed successfully

date Date

The date the payment was applied

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "amount": 55.39,
    "payment_method_id": 111,
    "type": "credit card",
    "response_message": "Successful.",
    "success": true,
    "reversed": true,
    "reversed_at": "2015-09-30",
    "date": "2015-09-23 16:55:12"
  }
}

Accounts

Accounts - Create account

Create a new account. There are items entered here such as the address and contact information that must be obtained from other endpoints. They are required here to meet the requirements with the Sonar application - a contact must have a physical address and primary contact when created.

https://example.sonar.software/api/v1/accounts

Parameter

Field Type Description
id optional Number

An ID for the account. The ID must be numeric and not currently in use. If you do not include an ID (which is the recommended method) then the next available ID will be automatically used. Once this is set, it cannot be changed.

name String

A name for the new account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups optional Array

An array of account group IDs, this can be referenced against /system/account_groups/:id

sub_accounts optional Array

An array of account IDs that you want to attach to this account as children

next_bill_date optional String

A YYYY-MM-DD formatted date that dictates when the account should next bill. Generally speaking, you should allow Sonar to automatically calculate this. The only time you should set it is if this customer specifically needs to bill on a future date that would not be the calculated date - for example, if this is a customer that is billed once every 6 months and they billed 2 months ago, you would need to manually set this to 4 months in the future. Whatever day is set on your next_bill_date will also be set as the future recurring billing day. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing

line1 String

The first line of the physical address

line2 optional String

The second line of the physical address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country. It is important to set this correctly as it will be used for calculating geo taxes

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal.

longitude Float

The longitude of the address, in decimal.

contact_name String

The name of the primary account contact

role String

The role of the primary account contact (e.g. CEO, Accountant)

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension. See the contact section of the API for an example

email_message_categories Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Create account

Create a new account. There are items entered here such as the address and contact information that must be obtained from other endpoints. They are required here to meet the requirements with the Sonar application - a contact must have a physical address and primary contact when created.

https://example.sonar.software/api/v1/accounts

Parameter

Field Type Description
name String

A name for the new account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups optional Array

An array of account group IDs, this can be referenced against /system/account_groups/:id

sub_accounts optional Array

An array of account IDs that you want to attach to this account as children

next_bill_date optional String

A YYYY-MM-DD formatted date that dictates when the account should next bill. Generally speaking, you should allow Sonar to automatically calculate this. The only time you should set it is if this customer specifically needs to bill on a future date that would not be the calculated date - for example, if this is a customer that is billed once every 6 months and they billed 2 months ago, you would need to manually set this to 4 months in the future. Whatever day is set on your next_bill_date will also be set as the future recurring billing day. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing

line1 String

The first line of the physical address

line2 optional String

The second line of the physical address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country. It is important to set this correctly as it will be used for calculating geo taxes

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal.

longitude Float

The longitude of the address, in decimal.

contact_name String

The name of the primary account contact

role optional String

The role of the primary account contact (e.g. CEO, Accountant)

email_address optional String

The email address of the contact

phone_numbers optional Object

An object representing the phone numbers on the account, where the property is the type of phone number it is (one of work, home, mobile, fax) and the value of the property is an object containing two properties, number and extension. See the contact section of the API for an example

email_message_categories optional Array

An array of IDs representing the email categories this contact should receive. You can get a descriptive string describing the category ID from /_data/email_categories.

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Delete account

Delete an account. Be careful when using this method! This will disable the accounts services and make all the data associated with this account inaccessible as soon as it is deleted.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field Type Description
id Number

The ID of the account

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "That account does not exist",
         "status_code": 404
     }
 }

Accounts - Get all accounts

Get a list of the accounts in the system

https://example.sonar.software/api/v1/accounts

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Jacob Kailing",
            "account_status_id": 1,
            "account_type_id": 1,
            "account_groups": [],
            "balance_due": 0,
            "balance_total": 0,
            "sub_accounts": [],
            "next_bill_date": "2015-10-01",
            "delinquent": false
        },
        {
            "id": 2,
            "name": "Horatio T Hornblower",
            "account_status_id": 1,
            "account_type_id": 1,
            "account_groups": [],
            "balance_due": 0,
            "balance_total": 0,
            "sub_accounts": [],
            "next_bill_date": "2015-11-03",
            "delinquent": true
        }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Accounts - Get individual account

Get an individual account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field Type Description
id Number

The ID of the account

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2018-03-04",
        "delinquent": false
    }
}

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field Type Description
id Number

The ID of the account group to update

name optional String

The name of the account

account_type_id optional Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id optional Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups optional Array

An array of account group IDs, this can be referenced against /system/account_groups/:id

sub_accounts optional Array

An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children

prorate Boolean

If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used

Default value: false

next_bill_date optional Date

If you would like to override the next bill date to a different date, it can be updated here in YYYY-MM-DD format. You should generally not do this, as you can cause serious billing issues - this is almost always only used when importing data from another system. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing. This requires account superuser permissions

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field Type Description
id Number

The ID of the account group to update

name optional String

The name of the account

account_type_id optional Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id optional Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups optional Array

An array of account group IDs, this can be referenced against /system/account_groups/:id

sub_accounts optional Array

An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children

prorate Boolean

If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used

Default value: false

next_bill_date optional Date

If you would like to override the next bill date to a different date, it can be updated here in YYYY-MM-DD format. You should generally not do this, as you can cause serious billing issues - this is almost always only used when importing data from another system. The day portion of next_bill_date cannot be higher than 28, as Sonar only allows 28 day billing. This requires account superuser permissions

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Accounts - Update account

Update an account.

https://example.sonar.software/api/v1/accounts/:id

Parameter

Field Type Description
id Number

The ID of the account group to update

name optional String

The name of the account

account_type_id optional Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id optional Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups optional Array

An array of account group IDs, this can be referenced against /system/account_groups/:id

sub_accounts optional Array

An array of account IDs that you want to attach to this account as children. If you submit this parameter, you must submit all the IDs that should be children - if you omit existing children, they will be attached. An empty array will detach all children

prorate Boolean

If you have account super user permissions, and you are changing the account status, set this to 'true' to prorate the change and 'false' to not prorate the change. If you do not have account superuser permissions, this value will be ignored and the system default prorating value will be used

Default value: false

Success 200

Field Type Description
id Number

The internal ID of the account

name String

The name of the account

account_type_id Number

An ID representing the type of account, this can be referenced against /system/account_types/:id

account_status_id Number

An ID representing the status of the account, this can be referenced against /system/account_statuses/:id

account_groups Array

An array of account group IDs that this account belongs to, this can be referenced against /system/account_groups/:id

balance_due Number

The sum of all remaining_due amounts on associated invoices

balance_total Number

The sum of all remaining_due amounts on associated invoices, plus any uninvoiced debits

sub_accounts Array

An array of account IDs that are children/sub accounts of this account

next_bill_date String

The date on which this account will next bill. This will be null if the account has never been activated

delinquent Boolean

Whether or not the account is currently delinquent

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Simon Westlake",
        "account_status_id": 1,
        "account_type_id": 1,
        "account_groups":  [],
        "balance_due": 0,
        "balance_total": 0,
        "sub_accounts": [],
        "next_bill_date": "2015-10-01",
        "delinquent": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "account_status_id": "The selected account status id is not valid.",
         },
         "status_code": 422
     }
 }

Address Lists

Address_Lists - Create a new address list

Create a new address list. If there are enabled, available inline devices in Sonar, this address list will be immediately created on them.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field Type Description
name String

The name of the address list

delinquent optional Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

Default value: 3

Allowed values: 1, 2, 3

active optional Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

Default value: 3

Allowed values: 1, 2, 3

account_groups optional Array

An array of account group IDs that are a relation to this address list.

account_types optional Array

An array of account type IDs that are a relation to this address list.

services optional Array

An array of data service IDs that are a relation to this address list.

account_statuses optional Array

An array of account status IDs that are a relation to this address list.

usage_based_billing_policies optional Array

An array of usage based billing policy IDs that are checked for caps being exceeded

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

usage_based_billing_policies Array

An array of usage based billing policy IDs that are checked for caps being exceeded

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "test",
    "delinquent": 3,
    "active": 3,
    "account_groups": [],
    "account_types": [],
    "services": [
      14,
      12
    ],
    "account_statuses": [],
    "usage_based_billing_policies": [
      6,
      5
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The address list name has already been taken.",
         },
         "status_code": 422
     }
 }

Address_Lists - Create a new address list

Create a new address list. If there are enabled, available inline devices in Sonar, this address list will be immediately created on them.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field Type Description
name String

The name of the address list

delinquent optional Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

Default value: 3

Allowed values: 1, 2, 3

active optional Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

Default value: 3

Allowed values: 1, 2, 3

account_groups optional Array

An array of account group IDs that are a relation to this address list.

account_types optional Array

An array of account type IDs that are a relation to this address list.

services optional Array

An array of data service IDs that are a relation to this address list.

account_statuses optional Array

An array of account status IDs that are a relation to this address list.

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

HTTP/1.1 201 OK
{
  "id": 34,
  "name": "Boneapart",
  "delinquent": 3,
  "active": 2,
  "account_groups": [],
  "account_types": [
    1
  ],
  "services": [],
  "account_statuses": []
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The address list name has already been taken.",
         },
         "status_code": 422
     }
 }

Address_Lists - Delete address list

Delete an address list. This will immediately remove the address list from all enabled inline devices in a good status.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list.

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the address list could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "Address list does not exist."
         },
         "status_code": 404
     }
 }

Address_Lists - Delete address list

Delete an address list. This will immediately remove the address list from all enabled inline devices in a good status.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list.

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the address list could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "Address list does not exist."
         },
         "status_code": 404
     }
 }

Address_Lists - Get all address lists

Get a list of address lists.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

usage_based_billing_policies Array

An array of usage based billing policy IDs that are checked for caps being exceeded

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "test",
      "delinquent": 3,
      "active": 3,
      "account_groups": [],
      "account_types": [],
      "services": [
        14,
        12
      ],
      "account_statuses": [],
      "usage_based_billing_policies": [
        6,
        5
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Address_Lists - Get all address lists

Get a list of address lists.

https://example.sonar.software/api/v1/network/provisioning/address_lists

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

HTTP/1.1 200 OK
{
  "data": [
        {
         "id": 23,
         "name": "Active",
         "delinquent": 3,
         "active": 1,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 24,
         "name": "Inactive",
         "delinquent": 3,
         "active": 2,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 25,
         "name": "Delinquent",
         "delinquent": 1,
         "active": 3,
         "account_groups": [],
         "account_types": [],
         "services": [],
         "account_statuses": []
       },
       {
         "id": 20,
         "name": "MyDataService",
         "delinquent": 3,
         "active": 3,
         "account_groups": [],
         "account_types": [],
         "services": [
           1
         ],
         "account_statuses": []
       }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Address_Lists - Get individual address list

Get an individual address list.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

usage_based_billing_policies Array

An array of usage based billing policy IDs that are checked for caps being exceeded

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "test",
    "delinquent": 3,
    "active": 3,
    "account_groups": [],
    "account_types": [],
    "services": [
      14,
      12
    ],
    "account_statuses": [],
    "usage_based_billing_policies": [
      6,
      5
    ]
  }
}

Address_Lists - Get individual address list

Get an individual address list.

https://example.sonar.software/api/v1/network/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": []
  }
}

Address_Lists - Update address list

Update an address list

https://example.sonar.software/api/v1/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list

name optional String

The name of the address list

delinquent optional Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active optional Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups optional Array

An array of account group IDs that are a relation to this address list.

account_types optional Array

An array of account type IDs that are a relation to this address list.

services optional Array

An array of data service IDs that are a relation to this address list.

account_statuses optional Array

An array of account status IDs that are a relation to this address list.

usage_based_billing_policies optional Array

An array of usage based billing policy IDs that are checked for caps being exceeded

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

usage_based_billing Array

policies An array of usage based billing policy IDs that are checked for caps being exceeded

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": [],
    "usage_based_billing_policies": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Address_Lists - Update address list

Update an address list

https://example.sonar.software/api/v1/provisioning/address_lists/:id

Parameter

Field Type Description
id Number

The ID of the address list

name optional String

The name of the address list

delinquent optional Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active optional Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups optional Array

An array of account group IDs that are a relation to this address list.

account_types optional Array

An array of account type IDs that are a relation to this address list.

services optional Array

An array of data service IDs that are a relation to this address list.

account_statuses optional Array

An array of account status IDs that are a relation to this address list.

Success 200

Field Type Description
id Number

The ID of the address list

name String

The name of the address list

delinquent Number

If this is 1, the list is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the list is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

account_groups Array

An array of account group IDs that are a relation to this address list.

account_types Array

An array of account type IDs that are a relation to this address list.

services Array

An array of data service IDs that are a relation to this address list.

account_statuses Array

An array of account status IDs that are a relation to this address list.

HTTP/1.1 200 OK
{
  "data": {
    "id": 23,
    "name": "Active",
    "delinquent": 3,
    "active": 1,
    "account_groups": [],
    "account_types": [],
    "services": [],
    "account_statuses": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Alerting Rotations

Alerting_Rotations - Create a new alerting rotation day/time

Create a new alerting rotation day/time.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success 200

Field Type Description
id Integer

The ID of the alerting rotation day/time.

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "day": 5,
    "start_timestamp": "08:35",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "data": {
     "id": 1,
     "day": 2,
     "start_timestamp": "8:0",
     "end_timestamp": "17:0"
   }
 }

Alerting_Rotations - Create a new alerting rotation

Create a new alerting rotation.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations

Parameter

Field Type Description
enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success 200

Field Type Description
id Integer

The ID of the alerting rotation.

enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "start": "start must be a date in YYYY-MM-DD format."
     },
     "status_code": 422
   }
 }

Alerting_Rotations - Delete a alerting rotation day/time

Delete a alerting rotation day/time

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

alerting_rotation_day_id Integer

The ID of the alerting rotation day/time

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the alerting rotation day/time could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation day/time does not exist.",
         "status_code": 404
     }
 }

Alerting_Rotations - Delete a alerting rotation

Delete a alerting rotation

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the alerting rotation could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation does not exist.",
         "status_code": 404
     }
 }

Alerting_Rotations - Get all alerting rotations

Get all alerting rotations

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the alerting rotation.

enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "enabled": true,
      "name": "Rotation 1 Updated",
      "start": "2016-12-15",
      "repetitions": 5,
      "infinite_repetitions": true,
      "weeks": 1,
      "warning_time_in_minutes_before_alerting": 10,
      "down_time_in_minutes_before_alerting": 5,
      "user_ids": [
        1
      ],
      "all_accounts": true,
      "all_network_sites": true,
      "all_inventory_models": true,
      "network_site_ids": [],
      "inventory_model_ids": [
        1,
        2
      ],
      "account_group_ids": [],
      "account_type_ids": [
        2,
        1
      ]
    },
    {
      "id": 3,
      "enabled": true,
      "name": "Another Rotation",
      "start": "2016-12-15",
      "repetitions": 5,
      "infinite_repetitions": true,
      "weeks": 1,
      "warning_time_in_minutes_before_alerting": 10,
      "down_time_in_minutes_before_alerting": 5,
      "user_ids": [
        1
      ],
      "all_accounts": true,
      "all_network_sites": true,
      "all_inventory_models": true,
      "network_site_ids": [],
      "inventory_model_ids": [
        1,
        2
      ],
      "account_group_ids": [],
      "account_type_ids": [
        2,
        1
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Alerting_Rotations - Get all alerting rotation day/times

Get all alerting rotation day/times

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the alerting rotation day/time.

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "day": 2,
      "start_timestamp": "08:00",
      "end_timestamp": "17:00"
    },
    {
      "id": 2,
      "day": 2,
      "start_timestamp": "08:35",
      "end_timestamp": "17:00"
    },
    {
      "id": 3,
      "day": 5,
      "start_timestamp": "08:35",
      "end_timestamp": "17:00"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Alerting_Rotations - Get an individual alerting rotation day/time

Get an individual alerting rotation day/time

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

alerting_rotation_day_id Integer

The ID of the alerting rotation day

Success 200

Field Type Description
id Integer

The ID of the alerting rotation day/time.

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 2,
    "start_timestamp": "08:00",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Get an individual alerting rotation

Get an individual alerting rotation

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

Success 200

Field Type Description
id Integer

The ID of the alerting rotation.

enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Update alerting rotation day/time

Update an existing alerting rotation day/time.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id/alerting_rotation_days/:alerting_rotation_day_id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation

alerting_rotation_day_id Integer

The ID of the alerting rotation day

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

Success 200

Field Type Description
id Integer

The ID of the alerting rotation day/time.

day Integer

An integer representing the day of the week, where 0 is Sunday and 6 is Saturday

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

A timestamp representing the start time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

end_timestamp Time

A timestamp representing the end time of the rotation for this day, in the Sonar timezone. The format should be HH:mm where HH is a 24 hour hour, and mm is a two digit minute.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 5,
    "start_timestamp": "08:35",
    "end_timestamp": "17:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Alerting_Rotations - Update alerting rotation

Update an existing alerting rotation.

https://example.sonar.software/api/v1/network/monitoring/alerting_rotations/:id

Parameter

Field Type Description
id Integer

The ID of the alerting rotation.

enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

Success 200

Field Type Description
id Integer

The ID of the alerting rotation.

enabled Boolean

Whether or not the rotation is enabled

name String

A name for the alerting rotation

start Date

A date when the rotation should begin

repetitions Integer

The number of times the rotation should repeat

weeks Integer

How frequently the rotation should repeat, in weeks. 1 means every week, 2 means every other week, 3 means on one week, off two weeks, on one week, etc.

infinite_repetitions Boolean

Should this rotation repeat forever? If this is true, repetitions is ignored.

warning_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a warning state before an alert is sent

down_time_in_minutes_before_alerting Integer

How long devices that this alerting rotation covers can be in a down state before an alert is sent

user_ids Array

An array of users that are in this rotation

all_accounts Boolean

If this is true, then the account_group_ids and account_type_ids values are ignored, and this rotation applies to all accounts

all_network_sites Boolean

If this is true, then the network_site_ids value is ignored, and this rotation applies to all network sites

all_inventory_models Boolean

If this is true, then the inventory_model_ids value is ignored, and this rotation applies to all inventory models

network_site_ids Array

An array of network site IDs that this rotation covers. You can use this to limit the network sites that will send alerts to the users in this rotation.

inventory_model_ids Array

An array of inventory model IDs that will push alerts into this rotation. You can use this to limit the types of devices that will send alerts to users in this rotation.

account_group_ids Array

An array of account groups that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

account_type_ids Array

An array of account types that will push alerts into this rotation. You can use this to limit the accounts that will send alerts to users in this rotation.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "enabled": true,
    "name": "Rotation 1 Updated",
    "start": "2016-12-15",
    "repetitions": 5,
    "infinite_repetitions": true,
    "weeks": 1,
    "warning_time_in_minutes_before_alerting": 10,
    "down_time_in_minutes_before_alerting": 5,
    "user_ids": [
      1
    ],
    "all_accounts": true,
    "all_network_sites": true,
    "all_inventory_models": true,
    "network_site_ids": [],
    "inventory_model_ids": [
      1,
      2
    ],
    "account_group_ids": [],
    "account_type_ids": [
      2,
      1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

CDRs

CDRs - Submit a standardized CDR for rating

Submit call records to be rated by Sonar. The records must be in a standardized format. When submitting records to this endpoint, batch them into sets of 5,000 records at a time. At this time, only 10 digit calls are supported for national calls (NANP.) Anything longer than 10 digits will be treated as international.

https://example.sonar.software/api/v1/system/voice/cdr_rating
{
   "voice_provider_id": 1,
   "records": [
       {
           "origination": "1234567890",
           "destination": "0111234657364",
           "call_start": "2016-08-11 09:43:21",
           "duration": 123
       },
       {
           "origination": "1234567891",
           "destination": "18006667777",
           "call_start": "2016-08-11 09:47:21",
           "duration": 38
       }
   ]
}

Parameter

Field Type Description
voice_provider_id Integer

The ID of the voice provider which these CDRs are for. This is how you specify which rate deck to use for these calls.

records Array

An array of records, the format of which is shown in the example below, and in the entries below this one.

origination String

The originating DID (10 digits, or 11 with a leading 1.)

destination String

The destination DID (Minimum of 10 digits)

call_start DateTime

The date and time the call was placed, in UTC in YYYY-MM-DD HH:mm:ss format. Hours should be in 24 hour format.

duration Integer

The duration of the call, in seconds

Success 200

Field Type Description
success Boolean

true if the records have been queued for rating.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

Contracts

Contracts - Create a new contract

Create a new contract from a contract template. A link to sign the contract will be emailed to the specified contact, as long as the contact has an email address.

https://example.sonar.software/api/v1/accounts/:account_id/contracts

Parameter

Field Type Description
account_id Integer

The ID of the account to assign the contract to

contract_template_id Integer

The ID of a contract template

contact_id Integer

The ID of a contact on the account specified in account_id. This contact will receive an email with a link to sign the contract.

custom_message optional String

If you'd like a customized message to be displayed on the contract signature page, then enter it here.

Success 200

Field Type Description
id Integer

The ID of the contract.

contract_name String

The name of the contract

contract_text String

The body of the contract, may contain some HTML.

contact_id Integer

The ID of the contact associated with the contract. Only valid while the contract is unsigned.

term_in_months Integer

The contract term in months, if it has one.

acceptance_datetime DateTime

The date and time the contract was signed, in UTC

expiration_date Date

The date the contract with expire, if it had a term. This is in the system timezone.

custom_message String

The custom message associated with the contract

signer_name String

The name the signer entered when signing the contract, if it is signed

signer_ip String

The IP address of the party that signed the contract, if it is signed

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "contract_name": "Example Contract",
    "contract_text": "Here is an example contract. Very nice.",
    "contact_id": 1,
    "term_in_months": 12,
    "acceptance_datetime": null,
    "expiration_date": null,
    "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
    "signer_name": null,
    "signer_ip": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 4xx
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Delete a contract

Delete a contract. Only unsigned contracts can be deleted.

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field Type Description
account_id Integer

The ID of the account.

id Integer

The ID of the contract

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the contract could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Contract does not exist.",
         "status_code": 404
     }
 }

Contracts - Get all contracts

Get all contracts

https://example.sonar.software/api/v1/accounts/:account_id/contracts

Parameter

Field Type Description
account_id Integer

The ID of the account you wish to return the contract list for

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the contract.

contract_name String

The name of the contract

contract_text String

The body of the contract, may contain some HTML.

contact_id Integer

The ID of the contact associated with the contract. Only valid while the contract is unsigned.

term_in_months Integer

The contract term in months, if it has one.

acceptance_datetime DateTime

The date and time the contract was signed, in UTC

expiration_date Date

The date the contract with expire, if it had a term. This is in the system timezone.

custom_message String

The custom message associated with the contract

signer_name String

The name the signer entered when signing the contract, if it is signed

signer_ip String

The IP address of the party that signed the contract, if it is signed

unique_link_key String

The unique key used on the Sonar contract signature page

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 7,
     "contract_name": "Example Contract",
     "contract_text": "Here is an example contract. Very nice!",
     "contact_id": 1,
     "term_in_months": 12,
     "acceptance_datetime": null,
     "expiration_date": null,
     "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
     "signer_name": null,
     "signer_ip": null,
     "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
   }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Contracts - Get an individual contract as base64

Get an individual contract as base64. This allows you to reconstruct the PDF, so you can present it in an external system (e.g. the customer portal.)

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id/base64

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the contract

Success 200

Field Type Description
base64 String

The base64 encoded contract

HTTP/1.1 200 OK
{
  "data": {
     "base64": "Q29uZ3JhdHVsYXRpb25zLCB5b3UgaGF2ZSBtYW5hZ2VkIHRvIGRlY29kZSBteSBzZWNyZXQgYmFzZTY0IGRhdGEhIFBsZWFzZSBkb24ndCBzaGFyZSB0aGUgY29udGVudHMgb2YgdGhpcyB3aXRoIGFueW9uZSAtIGl0J3MgYSBzZWNyZXQh"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Get an individual contract

Get an individual contract

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the contract

Success 200

Field Type Description
id Integer

The ID of the contract.

contract_name String

The name of the contract

contract_text String

The body of the contract, may contain some HTML.

contact_id Integer

The ID of the contact associated with the contract. Only valid while the contract is unsigned.

term_in_months Integer

The contract term in months, if it has one.

acceptance_datetime DateTime

The date and time the contract was signed, in UTC

expiration_date Date

The date the contract with expire, if it had a term. This is in the system timezone.

custom_message String

The custom message associated with the contract

signer_name String

The name the signer entered when signing the contract, if it is signed

signer_ip String

The IP address of the party that signed the contract, if it is signed

unique_link_key String

The unique key used on the Sonar contract signature page

HTTP/1.1 200 OK
{
  "data": {
     "id": 7,
     "contract_name": "Example Contract",
     "contract_text": "Here is an example contract. Very nice!",
     "contact_id": 1,
     "term_in_months": 12,
     "acceptance_datetime": null,
     "expiration_date": null,
     "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
     "signer_name": null,
     "signer_ip": null,
     "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Contracts - Update contract

Update an existing contract. The only thing that can be updated is the custom message - to make any other changes, delete and re-add.

https://example.sonar.software/api/v1/accounts/:account_id/contracts/:id

Parameter

Field Type Description
account_id Integer

The account ID

id Integer

The contract ID

custom_message String

The custom message to display when the contract is being signed.

contact_id Integer

The ID of the contact the contract should be emailed to. If this is changed, the contract will be emailed to the new contact.

Success 200

Field Type Description
id Integer

The ID of the contract.

contract_name String

The name of the contract

contract_text String

The body of the contract, may contain some HTML.

contact_id Integer

The ID of the contact associated with the contract. Only valid while the contract is unsigned.

term_in_months Integer

The contract term in months, if it has one.

acceptance_datetime DateTime

The date and time the contract was signed, in UTC

expiration_date Date

The date the contract with expire, if it had a term. This is in the system timezone.

custom_message String

The custom message associated with the contract

signer_name String

The name the signer entered when signing the contract, if it is signed

signer_ip String

The IP address of the party that signed the contract, if it is signed

unique_link_key String

The unique key used on the Sonar contract signature page

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "contract_name": "Example Contract",
    "contract_text": "Here is an example contract. Very nice.",
    "contact_id": 1,
    "term_in_months": 12,
    "acceptance_datetime": null,
    "expiration_date": null,
    "custom_message": "Hello John! Please sign this contract so we can get the ball rolling on synergizing your ability to evaluate our ground breaking product!",
    "signer_name": null,
    "signer_ip": null,
    "unique_link_key": "72ULw3Kn4mAeRnLAyrhC6XFowRdIWV7UEtyEFYQrfsILwvJv588660c0e2c12"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Custom Fields

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site", "jobs"

entity_id Number

The ID of the entity

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site"

entity_id Number

The ID of the entity

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee"

entity_id Number

The ID of the entity

Success 200

Field Type Description
data String

The content of the custom field

custom_field_name String

The name of the custom field. You should generally use the field ID programatically, as the name can change

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer Alive?",
      "data": false
    },
    {
      "custom_field_id": 3,
      "custom_field_name": "Please enter some text in this field",
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get custom fields for entity

Get a list of the custom fields assigned to this entity that have information set.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account"

entity_id Number

The ID of the entity

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data": [
    {
      "custom_field_id": 4,
      "data": false
    },
    {
      "custom_field_id": 3,
      "data": "Some text"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site", "jobs"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field Type Description
data String

The content of the custom field

custom_field_name String

The name of the custom field. You should generally use the field ID programatically, as the name can change

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer A Walrus?",
      "data": false
    }
}

Custom_Fields - Get individual custom field for entity

Get a specific custom field for a specific entity, by custom field ID.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 200 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site", "jobs"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

data String

The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee", "network_site"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

data String

The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account", "generic_inventory_assignee"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

data String

The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field Type Description
data String

The content of the custom field

custom_field_name String

The name of the custom field. You should generally use the field ID programatically, as the name can change

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "custom_field_name": "Is The Customer Partial to Pumpkin Pie?",
      "data": false
    }
}

Custom_Fields - Update a custom field for an entity

Update the data in a custom field for an entity.

https://example.sonar.software/api/v1/entity_custom_fields/:entity/:entity_id/:custom_field_id

Parameter

Field Type Description
entity String

The type of entity to get custom fields for.

Allowed values: "account"

entity_id Number

The ID of the entity

custom_field_id Number

The ID of the custom field (provided at /system/custom_fields)

data String

The content of the custom field. If the custom field is a checkbox, this must be a boolean. If it is a select/dropdown, it must be one of the predefined fields allowed. If it is a date, it must be YYYY-MM-DD format.

Success 200

Field Type Description
data String

The content of the custom field

custom_field_id Number

A unique ID that matches the ID of a custom field defined at /system/custom_fields

HTTP/1.1 201 OK
{
  "data":
    {
      "custom_field_id": 4,
      "data": false
    }
}

Customer Portal

Customer_Portal - Look up an email address

Look up an email address to see if it is valid. This is designed to be used for account creation, or resetting forgotten passwords. This will return the first contact found with the email address provided, that is a primary contact, and has no username associated with it. This endpoint is not throttled - you must throttle your look up function or this presents a security risk!

https://example.sonar.software/api/v1/customer_portal/email_lookup

Parameter

Field Type Description
email_address String

The email address to look up

check_if_available Boolean

If true, this checks if the contact is primary, and it does not have a username. If this is false, then it will check if the account is primary, and it does have a username.

Default value: true

Success 200

Field Type Description
email_address String

The email address of the contact

account_id Number

The account ID of the contact

contact_id Number

The ID of the contact

username String

The current username for this contact, if one exists

HTTP/1.1 201 OK
{
  "data": {
    "email_address": "someone@example.com",
    "account_id": 1,
    "contact_id": 1,
    "username": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "The email address was not found.",
     "status_code": 422
   }
 }

Customer_Portal - Validate credentials

Validate a contact's username and password for customer portal access. This will validate if the username and password matches, and the contact is a primary contact. You should only use this endpoint if you are building your own customer portal, and you want to hook into the username/password storage on a Sonar contact. This endpoint is not throttled - you must throttle your authentication function or this presents a security risk!

https://example.sonar.software/api/v1/customer_portal/auth

Parameter

Field Type Description
username String

The case-insensitive username to use for authentication

password Number

The case-sensitive password to use for authentication

Success 200

Field Type Description
contact_name String

The name of the contact

email_address String

The email address of the contact

account_id Number

The account ID of the contact

contact_id Number

The ID of the contact

username String

The username that was authenticated

HTTP/1.1 201 OK
{
  "data": {
    "contact_name": "John Doe",
    "email_address": "someone@example.com",
    "account_id": 1,
    "contact_id": 1,
    "username": "testtest123"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Invalid username or password.",
     "status_code": 422
   }
 }

DHCP Server Identifiers

DHCP_Server_Identifiers - Create a new DHCP server identifier

Create a new DHCP server identifier.

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers

Parameter

Field Type Description
name String

A name for the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

Success 200

Field Type Description
id Integer

The ID of the DHCP server identifier.

name String

The name of the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Papaya",
    "ip_pool_ids": [
       1,
       3
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

DHCP_Server_Identifiers - Delete a DHCP server identifier

Delete a DHCP server identifier

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field Type Description
id Integer

The ID of the DHCP server identifier

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the DHCP server identifier could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "DHCP server identifier does not exist.",
         "status_code": 404
     }
 }

DHCP_Server_Identifiers - Get all DHCP server identifiers

Get all DHCP server identifiers

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the DHCP server identifier.

name String

The name of the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

HTTP/1.1 200 OK
{
  "data": [
      {
      "id": 2,
      "name": "Papaya",
      "ip_pool_ids": [
         1,
         3
      ]
    },
    {
      "id": 3,
      "name": "SteelBlue",
      "ip_pool_ids": [
         4,
         6,
         12
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DHCP_Server_Identifiers - Get an individual DHCP server identifier

Get an individual DHCP server identifier

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field Type Description
id Integer

The ID of the DHCP server identifier

Success 200

Field Type Description
id Integer

The ID of the DHCP server identifier.

name String

The name of the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

HTTP/1.1 200 OK
{
  "data": {
     "id": 3,
     "name": "SteelBlue",
     "ip_pool_ids": [
        4,
        6,
        12
     ]
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DHCP_Server_Identifiers - Update DHCP server identifier

Update an existing DHCP server identifier.

https://example.sonar.software/api/v1/network/provisioning/dhcp_server_identifiers/:id

Parameter

Field Type Description
name String

A name for the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

Success 200

Field Type Description
id Integer

The ID of the DHCP server identifier.

name String

The name of the DHCP server identifier

ip_pool_ids Array

An array of IP pool IDs that should be associated with this identifier

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DHCP Servers

DHCP_Servers - Get all DHCP servers

Get a list of DHCP servers.

https://example.sonar.software/api/v1/network/provisioning/dhcp_servers

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the DHCP server

ip_address String

The IP address of the DHCP server

name String

The name provided for the DHCP server

type String

The type of DHCP server that this is

Allowed values: "mikrotik"

controls_all_pools Boolean

If this DHCP server stores leases for all pools defined in Sonar or not

failures Number

The number of failures writing leases that have been encountered since last rewrite/reset

device_status Boolean

Whether or not the device is in a good status. Devices with a status of 'false' will not have leases written.

status_message String

A message describing why the device is in a bad status, if device_status is false.

ip_pools Array

If controls_all_pools is false, this will be an array of IP pool IDs that the server controls.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "ip_address": "192.168.1.51",
      "name": "MikroTik",
      "enabled": true,
      "type": "mikrotik",
      "controls_all_pools": true,
      "failures": 0,
      "device_status": true,
      "status_message": null,
      "ip_pools": []
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DHCP_Servers - Get individual DHCP server

Get a single DHCP server

https://example.sonar.software/api/v1/network/provisioning/dhcp_servers/:id

Parameter

Field Type Description
id Number

The ID of the DHCP server

Success 200

Field Type Description
id Number

The ID of the DHCP server

ip_address String

The IP address of the DHCP server

name String

The name provided for the DHCP server

type String

The type of DHCP server that this is

Allowed values: "mikrotik"

controls_all_pools Boolean

If this DHCP server stores leases for all pools defined in Sonar or not

failures Number

The number of failures writing leases that have been encountered since last rewrite/reset

device_status Boolean

Whether or not the device is in a good status. Devices with a status of 'false' will not have leases written.

status_message String

A message describing why the device is in a bad status, if device_status is false.

ip_pools Array

If controls_all_pools is false, this will be an array of IP pool IDs that the server controls.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "ip_address": "192.168.1.51",
    "name": "MikroTik",
    "enabled": true,
    "type": "mikrotik",
    "controls_all_pools": true,
    "failures": 0,
    "device_status": true,
    "status_message": null,
    "ip_pools": []
  }
}

DIDs

DIDs - Delete a DID

Delete a DID

https://example.sonar.software/api/v1/system/voice/dids/:id

Parameter

Field Type Description
id Number

The ID of the DID

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the DID could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "DID does not exist.",
         "status_code": 404
     }
 }

DIDs - Get all DIDs

Get all DIDs

https://example.sonar.software/api/v1/system/voice/dids

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

account_id Integer

The account ID the DID is assigned to

service_id Integer

The ID of the voice service the DID is associated with

rate_center_id Integer

The ID of the rate center the DID is assigned to

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 7,
     "did": "1234567892",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   },
   {
     "id": 8,
     "did": "1234567893",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   },
   {
     "id": 9,
     "did": "1111112022",
     "account_id": null,
     "service_id": null,
     "rate_center_id": 1
   }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

DIDs - Get an individual DID

Get an individual DID

https://example.sonar.software/api/v1/system/voice/dids/:id

Parameter

Field Type Description
id Number

The ID of the DID

Success 200

Field Type Description
id Number

The ID of the DID.

did String

The DID

account_id Integer

The account ID the DID is assigned to

service_id Integer

The ID of the voice service the DID is associated with

rate_center_id Integer

The ID of the rate center the DID is assigned to

HTTP/1.1 200 OK
{
  "data": {
    "id": 8,
    "did": "1234567893",
    "account_id": null,
    "service_id": null,
    "rate_center_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

DIDs - Mass add DIDs

This endpoint allows you to import a large quantity of DIDs at once. This is used to add new, available DIDs to Sonar. When importing very large quantities of DIDs, split them into batches and import 5000 at a time. Sonar currently only supports 10 digit DIDs.

https://example.sonar.software/api/v1/system/voice/dids

{
  "dids": [
      "1234567890",
      "0987654321"
  ],
  "rate_center_id": 1
}

Parameter

Field Type Description
dids Array

An array of ten digit DIDs

rate_center_id Integer

The ID of the rate center to add these DIDs to

Success 200

Field Type Description
success Boolean

Will be true if the DIDs were successfully added.

HTTP/1.1 201 OK
{
  "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission contains duplicate DIDs. All DIDs must be unique."
     "status_code": 422
   }
 }

Data

Data - Email categories

Get a list of email categories. These are used when setting email category preferences on contacts. This returns an array of objects.

https://example.sonar.software/api/v1/_data/email_categories

Success 200

Field Type Description
id Number

The ID of the email category

name String

A name (localized to the system language) that describes the category

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Financial"
    },
    {
      "id": 3,
      "name": "General"
    },
    {
      "id": 4,
      "name": "Service Related"
    },
    {
      "id": 5,
      "name": "Outage Notifications"
    }
  ]
}

Data - Get Sonar version

Get the version of this Sonar instance.

https://example.sonar.software/api/v1/_data/version

Success 200

Field Type Description
version String

The software version of Sonar.

HTTP/1.1 200 OK
{
  "data": {
    "version": "1.2.38"
  }
}

Data - Supported counties

Get a list of counties for a US state. These are mainly used when configuring geotaxes.

https://example.sonar.software/api/v1/_data/counties/:subdivision

Parameter

Field Type Description
subdivision String

A US subdivision string obtained from /_data/subdivisions/US

Success 200

Field Type Description
data Array

An array containing all counties for that state.

HTTP/1.1 200 OK
{
  "data": [
    "Adams Co.",
    "Ashland Co.",
    "Barron Co.",
    "Bayfield Co.",
    "Brown Co.",
    "Buffalo Co.",
    "Burnett Co.",
    "Calumet Co.",
    "Chippewa Co.",
    "Clark Co.",
    "Columbia Co.",
    "Crawford Co.",
    "Dane Co.",
    "Dodge Co.",
    "Door Co.",
    "Douglas Co.",
    "Dunn Co.",
    "Eau Claire Co.",
    "Florence Co.",
    "Fond du Lac Co.",
    "Forest Co.",
    "Grant Co.",
    "Green Co.",
    "Green Lake Co.",
    "Iowa Co.",
    "Iron Co.",
    "Jackson Co.",
    "Jefferson Co.",
    "Juneau Co.",
    "Kenosha Co.",
    "Kewaunee Co.",
    "La Crosse Co.",
    "Lafayette Co.",
    "Langlade Co.",
    "Lincoln Co.",
    "Manitowoc Co.",
    "Marathon Co.",
    "Marinette Co.",
    "Marquette Co.",
    "Menominee Co.",
    "Milwaukee Co.",
    "Monroe Co.",
    "Oconto Co.",
    "Oneida Co.",
    "Outagamie Co.",
    "Ozaukee Co.",
    "Pepin Co.",
    "Pierce Co.",
    "Polk Co.",
    "Portage Co.",
    "Price Co.",
    "Racine Co.",
    "Richland Co.",
    "Rock Co.",
    "Rusk Co.",
    "St. Croix Co.",
    "Sauk Co.",
    "Sawyer Co.",
    "Shawano Co.",
    "Sheboygan Co.",
    "Taylor Co.",
    "Trempealeau Co.",
    "Vernon Co.",
    "Vilas Co.",
    "Walworth Co.",
    "Washburn Co.",
    "Washington Co.",
    "Waukesha Co.",
    "Waupaca Co.",
    "Waushara Co.",
    "Winnebago Co.",
    "Wood Co."
  ]
}

Data - Supported countries

Get a list of supported countries. The object property is the correct value to use when setting a country on an entity. The value is the name of the country.

https://example.sonar.software/api/v1/_data/countries

Success 200

Field Type Description
data Object

An object containing all supported countries.

HTTP/1.1 200 OK
{
    "data": {
       "US": "United States",
       "CA": "Canada",
       "AF": "Afghanistan",
       "AL": "Albania",
       "DZ": "Algeria",
       "AS": "American Samoa",
       //etc etc
   }
}

Data - Supported locales

Get a list of supported locales.

https://example.sonar.software/api/v1/_data/locales

Success 200

Field Type Description
data Object

An object containing all supported locales

HTTP/1.1 200 OK
{
    "data": {
       "en": "English (US)",
       "es": "Español",
       "fr": "Français"
       }
   }
}

Data - Supported subdivisions

Get a list of supported subdivisions. A subdivision is a geographical area within a country - for example, subdivisions in the USA are states, in Canada they are provinces. The :country parameter should be a country code returned from /_data/countries.

https://example.sonar.software/api/v1/_data/subdivisions/:country

Parameter

Field Type Description
country String

A two character country code obtained from /_data/countries

Success 200

Field Type Description
data Object

An object containing all supported subdivisions for the country.

HTTP/1.1 200 OK
{
  "data": {
    "Alabama": "Alabama",
    "Alaska": "Alaska",
    "American Samoa": "American Samoa",
    "Arizona": "Arizona",
    "Arkansas": "Arkansas",
    "California": "California",
    "Colorado": "Colorado",
    "Connecticut": "Connecticut",
    "Delaware": "Delaware",
    "District of Columbia": "District of Columbia",
    "Florida": "Florida",
    "Georgia": "Georgia",
    "Guam": "Guam",
    "Hawaii": "Hawaii",
    "Idaho": "Idaho",
    "Illinois": "Illinois",
    "Indiana": "Indiana",
    "Iowa": "Iowa",
    "Kansas": "Kansas",
    "Kentucky": "Kentucky",
    "Louisiana": "Louisiana",
    "Maine": "Maine",
    "Maryland": "Maryland",
    "Massachusetts": "Massachusetts",
    "Michigan": "Michigan",
    "Minnesota": "Minnesota",
    "Mississippi": "Mississippi",
    "Missouri": "Missouri",
    "Montana": "Montana",
    "Nebraska": "Nebraska",
    "Nevada": "Nevada",
    "New Hampshire": "New Hampshire",
    "New Jersey": "New Jersey",
    "New Mexico": "New Mexico",
    "New York": "New York",
    "North Carolina": "North Carolina",
    "North Dakota": "North Dakota",
    "Northern Mariana Islands": "Northern Mariana Islands",
    "Ohio": "Ohio",
    "Oklahoma": "Oklahoma",
    "Oregon": "Oregon",
    "Pennsylvania": "Pennsylvania",
    "Puerto Rico": "Puerto Rico",
    "Rhode Island": "Rhode Island",
    "South Carolina": "South Carolina",
    "South Dakota": "South Dakota",
    "Tennessee": "Tennessee",
    "Texas": "Texas",
    "United States Minor Outlying Islands": "United States Minor Outlying Islands",
    "Utah": "Utah",
    "Vermont": "Vermont",
    "Virgin Islands, U.S.": "Virgin Islands, U.S.",
    "Virginia": "Virginia",
    "Washington": "Washington",
    "West Virginia": "West Virginia",
    "Wisconsin": "Wisconsin",
    "Wyoming": "Wyoming"
  }
}

Data - Supported timezones

Get a list of supported timezones. The object property is the correct value to use when setting a timezone. The value is the translated string representing the timezone in the locale of the application.

https://example.sonar.software/api/v1/_data/timezones

Success 200

Field Type Description
data Object

An object containing all supported timezones.

HTTP/1.1 200 OK
{
    "data": {
       "Africa/Abidjan": "Africa/Abidjan",
       "Africa/Accra": "Africa/Accra",
       "Africa/Addis_Ababa": "Africa/Addis_Ababa",
       "Africa/Algiers": "Africa/Algiers",
       "Africa/Asmara": "Africa/Asmara",
       "Africa/Bamako": "Africa/Bamako",
       "Africa/Bangui": "Africa/Bangui",
       "Africa/Banjul": "Africa/Banjul",
       "Africa/Bissau": "Africa/Bissau",
       "Africa/Blantyre": "Africa/Blantyre",
       "Africa/Brazzaville": "Africa/Brazzaville",
       //etc etc
   }
}

Data - Validate an address

Validate an address for proper entry into Sonar. All addresses that you plan to enter should be run through this function.

https://example.sonar.software/api/v1/_data/validate_address

Parameter

Field Type Description
line1 String

The first address line (e.g. 123 Main St)

city String

The city (e.g. London)

state String

The state/province/subdivision (e.g. Texas)

country String

A 2 character ISO country code (e.g. US, GB, FR, DE)

Success 200

Field Type Description
line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

The county, for US addresses

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

HTTP/1.1 200 OK
{
  "data": {
    "line1": "615 N 6th St",
    "city": "Sheboygan",
    "state": "WI",
    "county": "Sheboygan Co.",
    "country": "US",
    "zip": "53081",
    "latitude": 43.750915527344,
    "longitude": -87.708717346191
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "The address could not be validated."
         "status_code": 422
     }
 }

Files

Files - Delete file

Delete a file. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field Type Description
entity_id Number

The ID of the entity

entity String

The type of entity (e.g. accounts, ticket_replies)

file_id Number

The ID of the file

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the file could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "File does not exist.",
         "status_code": 404
     }
 }

Files - Get all files

Get a list of files available on a specific entity. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:id/files

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the entity

entity String

The type of entity

Success 200

Field Type Description
id Number

The internal id of the file

filename String

The original filename

size_in_bytes Number

The size of the file in bytes

description String

The description entered for the file when it was uploaded

mime_type String

The MIME type of the file

uploader String

The username of the user that uploaded the file

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "filename": "HC04364756.pdf",
      "size_in_bytes": 76414,
      "description": "This is a contract!",
      "mime_type": "application/pdf",
      "uploader": "admin"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Files - Get individual file

Get an individual file. This will return the file details and the base64 data which can be decoded to create the file itself. Only entities that support files can be input to this endpoint. To get a valid entity name, use the portion of the route that corresponds to the entity in another API call - for example, the entity for an account is 'accounts', for ticket replies, it is 'ticket_replies'.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field Type Description
entity_id Number

The ID of the entity

entity String

The type of entity (e.g. accounts, ticket_replies)

file_id Number

The ID of the file

Success 200

Field Type Description
id Number

The internal id of the file

filename String

The original filename

size_in_bytes Number

The size of the file in bytes

description String

The description entered for the file when it was uploaded

mime_type String

The MIME type of the file

uploader String

The username of the user that uploaded the file

base64_data String

The base64 data for the file

HTTP/1.1 200 OK
{
    "data":
    {
      "id": 2,
      "filename": "my eighty ninth file upload.txt",
      "size_in_bytes": 19,
      "description": "This is a small file!",
      "mime_type": "text/plain",
      "uploader": "admin",
      "base64_data": "U29uYXIgaXMgdGhlIGJlc3QhCg=="
    }
}

Files - Update file details

Update details on a file. You can only change the description or the filename. To change file contents, delete it and upload a new one.

https://example.sonar.software/api/v1/:entity/:entity_id/files/:file_id

Parameter

Field Type Description
entity_id Number

The ID of the entity

entity String

The name of the entity (e.g. accounts, ticket_replies)

file_id Number

The ID of the file

description optional String

A description for the file

filename optional String

A filename for the file (with extension) - e.g. myfile.pdf, myfile.png

Success 200

Field Type Description
id Number

The internal id of the file

filename String

The original filename

size_in_bytes Number

The size of the file in bytes

description String

The description entered for the file when it was uploaded

mime_type String

The MIME type of the file

uploader String

The username of the user that uploaded the file

base64_data String

The base64 data for the file

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
      "filename": "HC04364756.pdf",
      "size_in_bytes": 76414,
      "description": "This is a contract!",
      "mime_type": "application/pdf",
      "uploader": "admin"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "file": "File ID not found."
         },
         "status_code": 422
     }
 }

Files - Upload a new file

Upload a new file to the entity. Images uploaded will be automatically converted to JPEG format and resized to a max of 2048x2048.

https://example.sonar.software/api/v1/:entity/:id/files

Parameter

Field Type Description
entity String

The name of the entity (e.g. accounts, ticket_replies)

id Number

The ID of the entity

description optional String

A description for the file

base64_data String

The file, base64 encoded

filename String

A filename for the file (with extension) - e.g. myfile.pdf, myfile.png

Success 200

Field Type Description
id Number

The internal id of the file

filename String

The original filename

size_in_bytes Number

The size of the file in bytes

description String

The description entered for the file when it was uploaded

mime_type String

The MIME type of the file

uploader String

The username of the user that uploaded the file

HTTP/1.1 201 OK
{
    "data":
    {
      "id": 2,
      "filename": "my first file upload.pdf",
      "size_in_bytes": 489384,
      "description": "This is a contract also!",
      "mime_type": "application/pdf",
      "uploader": "admin"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Financial

Financial - Create geotax

Create a new geographical tax. You must specify at least one geographical variable for automatic assignment to accounts based on address.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip optional String

A valid ZIP/postal code

zip_partial_match optional Boolean

Whether or not this geotax supports partial matching on a ZIP

Default value: false

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip optional String

A valid ZIP/postal code

zip_partial_match Boolean

Whether or not this geotax supports partial matching on a ZIP

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": null,
    "zip_partial_match": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Create geotax

Create a new geographical tax. You must specify at least one geographical variable for automatic assignment to accounts based on address.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Create tax

Create a new tax.

https://example.sonar.software/api/v1/financial/taxes

Parameter

Field Type Description
name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success 200

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "VAT",
    "application": "percentage",
    "type": "global",
    "rate": "20"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Financial - Delete geotax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the geotax could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Geotax not found",
         "status_code": 404
     }
 }

Financial - Delete tax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field Type Description
id Number

The ID of the tax

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Tax deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the tax could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Tax not found",
         "status_code": 404
     }
 }

Financial - Delete geotax

Delete a tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the geotax could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Geotax not found",
         "status_code": 404
     }
 }

Financial - Get all geotaxes for a tax

Get a list of all the geographic area taxes configured for a geographical tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field Type Description
id Number

The ID of the tax

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision String

A valid subdivision obtained from /_data/subdivisions

city String

A valid city

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip String

A valid ZIP/postal code

zip_partial_match Boolean

Whether or not this geotax supports partial matching on a ZIP

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Milwaukee County",
      "rate": "0.4",
      "subdivision": "Wisconsin",
      "city": "",
      "county": "Milwaukee Co.",
      "zip": "",
      "zip_partial_match": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get all geotaxes for a tax

Get a list of all the geographic area taxes configured for a geographical tax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes

Parameter

Field Type Description
id Number

The ID of the tax

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Milwaukee County",
      "rate": "0.4",
      "subdivision": "Wisconsin",
      "city": "",
      "county": "Milwaukee Co.",
      "zip": ""
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get all taxes

Get a list of all configured taxes.

https://example.sonar.software/api/v1/financial/taxes

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

 HTTP/1.1 200 OK
 {
  "data": [
    {
      "id": 1,
      "name": "$9 Flat Tax",
      "application": "flat",
      "type": "global",
      "rate": "9"
    },
    {
      "id": 2,
      "name": "3% Tax Rate",
      "application": "percentage",
      "type": "global",
      "rate": "3"
    },
    {
      "id": 3,
      "name": "Some other tax",
      "application": "flat",
      "type": "global",
      "rate": "2"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Financial - Get individual geo tax

Get an individual geotax from a parent tax

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision String

A valid subdivision obtained from /_data/subdivisions

city String

A valid city

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip String

A valid ZIP/postal code

zip_partial_match Boolean

Whether or not this geotax supports partial matching on a ZIP

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Milwaukee County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": "",
    "county": "Milwaukee Co.",
    "zip": "",
    "zip_partial_match": false
  }
}

Financial - Get individual geo tax

Get an individual geotax from a parent tax

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Milwaukee County",
    "rate": "0.4",
    "subdivision": "Wisconsin",
    "city": "",
    "county": "Milwaukee Co.",
    "zip": ""
  }
}

Financial - Get individual tax

Get an individual tax

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field Type Description
id Number

The ID of the tax

Success 200

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "$9 Flat Tax",
    "application": "flat",
    "type": "global",
    "rate": "9"
  }
}

Financial - Update geotax

Update a geotax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax.

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip optional String

A valid ZIP/postal code

zip_partial_match optional Boolean

Whether or not this geotax supports partial matching on a ZIP

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision String

A valid subdivision obtained from /_data/subdivisions

city String

A valid city

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip String

A valid ZIP/postal code

zip_partial_match Boolean

Whether or not this geotax supports partial matching on a ZIP

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "1.0",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": "12345",
    "zip_partial_match": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Update geotax

Update a geotax.

https://example.sonar.software/api/v1/financial/taxes/:id/geotaxes/:geotaxid

Parameter

Field Type Description
id Number

The ID of the tax

geotaxid Number

The ID of the geotax.

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

Success 200

Field Type Description
id Number

The ID of the geotax

name String

A descriptive name for the geotax

rate Number

The rate for the tax. This is either a percentage or a flat rate, depending on the configuration of the parent tax.

subdivision optional String

A valid subdivision obtained from /_data/subdivisions

city optional String

A valid city

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

A valid ZIP/postal code

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Sheboygan County",
    "rate": "1.0",
    "subdivision": "Wisconsin",
    "city": null,
    "county": "Sheboygan Co.",
    "zip": "12345"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Sheboygan Co. is not a valid county for the subdivision New York",
     "status_code": 422
   }
 }

Financial - Update tax

Update a tax.

https://example.sonar.software/api/v1/financial/taxes/:id

Parameter

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

Success 200

Field Type Description
id Number

The ID of the tax

name String

A descriptive name for the tax

application String

Either flat or percentage

Allowed values: "flat", "percentage"

type String

Either global or geo(graphical)

Allowed values: "global", "geo"

rate Number

The tax rate, a currency amount for flat and a percentage for percentage based taxes.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "VAT",
    "application": "percentage",
    "type": "global",
    "rate": "21"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

General Ledger Codes

General_Ledger_Codes - Create a new general ledger code

Create a new general ledger code.

https://example.sonar.software/api/v1/financial/general_ledger_codes

Parameter

Field Type Description
code String

A code for the general ledger code

description String

A description for the general ledger code

Success 200

Field Type Description
id Number

The ID of the general ledger code.

code String

A code for the general ledger code

description String

A description for the general ledger code

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "code": "12345",
    "description": "Internet Access"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "code "The code must be unique."
     },
     "status_code": 422
   }
 }

General_Ledger_Codes - Delete a general ledger code

Delete a general ledger code

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field Type Description
id Number

The ID of the general ledger code

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the general ledger code could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "general ledger code does not exist.",
         "status_code": 404
     }
 }

General_Ledger_Codes - Get all general ledger codes

Get all general ledger codes

https://example.sonar.software/api/v1/financial/general_ledger_codes

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the general ledger code.

code String

A code for the general ledger code

description String

A description for the general ledger code

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "code": "1000",
      "description": "test test"
    },
    {
      "id": 3,
      "code": "2010",
      "description": "test test test!"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

General_Ledger_Codes - Get an individual general ledger code

Get an individual general ledger code

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field Type Description
id Number

The ID of the general ledger code

Success 200

Field Type Description
id Number

The ID of the general ledger code.

HTTP/1.1 200 OK
{
  "data": {
    "id": 4,
    "code": "12345",
    "description": "Internet Access"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

General_Ledger_Codes - Update general ledger code

Update an existing general ledger code.

https://example.sonar.software/api/v1/financial/general_ledger_codes/:id

Parameter

Field Type Description
id Number

The general ledger code ID

code optional String

A code for the general ledger code

description optional String

A description for the general ledger code

Success 200

Field Type Description
id Number

The ID of the general ledger code.

code String

A code for the general ledger code

description String

A description for the general ledger code

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "code": "123456",
    "description": "Internet Access"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 422
 {
   "error": {
     "message": {
       "code": "The code has already been taken."
     },
     "status_code": 422
   }
 }

IPAM

IPAM

Lookup an individual IP address

https://example.sonar.software/api/v1/network/ipam/ip_lookup?ip=:ip

Parameter

Field Type Description
ip String

The IP address to lookup. Can be an IPv4/IPv6 address or subnet.

Success 200

Field Type Description
existing_assignment Object

If this IP is currently assigned to an entity, the details will be contained within this object. Example below.

historical_assignments Array

If this IP was previously assigned to other entities, this array will contain objects detailing who and when. Example below.

HTTP/1.1 200 OK
{
  "data": {
    "existing_assignment": {
      "subnet": "10.0.0.2",
      "account_id": 48,
      "soft": false,
      "subnet_name": "10.0.0.0/8",
      "ip_pool_name": "Test",
      "account_name": "West Allis Prep School"
    },
    "historical_assignments": [
      {
        "subnet": "10.0.0.2",
        "removed_datetime": "2017-02-04 15:57:22",
        "assigned_datetime": "2017-02-04 15:54:06",
        "soft": false,
        "name": "Jim Patient",
        "account_id": 1,
        "from": "Feb 4, 2017 09:54:06",
        "to": "Feb 4, 2017 09:57:22"
      }
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

IPAM - Create a new IP pool

Create a new IP pool. IP pools can only be created in IPv4 subnets.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field Type Description
supernet_id Integer

The ID of the supernet

subnet_id Integer

The ID of the subnet

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

dhcp_server_identifier_id Integer

The ID of a DHCP server identifier to use for this pool. Set to null to use no identifier.

Success 200

Field Type Description
id Integer

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

dhcp_server_identifier_id Integer

The DHCP server identifier used for this pool. Will be null if unset.

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
     ],
     "dhcp_server_identifier_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": "The pool does not fit within the subnet.",
     "status_code": 422
   }
 }

IPAM - Create a new IP pool

Create a new IP pool. IP pools can only be created in IPv4 subnets.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field Type Description
supernet_id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

Success 200

Field Type Description
id Number

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "The pool does not fit within the subnet.",
     "status_code": 422
   }
 }

IPAM - Create a new subnet

Create a new subnet. A subnet is a subdivided piece of a supernet, and can be used to assign IPs to various entities within Sonar, or used to build pools.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field Type Description
name String

A descriptive name for the subnet.

subnet String

The network address and CIDR prefix (e.g. 10.0.0.0/8)

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site that this subnet is deployed from.

inline_devices optional Array

An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

poller_id optional Number

The ID of the poller responsible for this subnet

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

poller_id Number

The ID of the poller responsible for this subnet

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [
       1
    ],
    "poller_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps subnet My first Subnet!.",
     "status_code": 422
   }
 }

IPAM - Create a new subnet

Create a new subnet. A subnet is a subdivided piece of a supernet, and can be used to assign IPs to various entities within Sonar, or used to build pools.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field Type Description
name String

A descriptive name for the subnet.

subnet String

The network address and CIDR prefix (e.g. 10.0.0.0/8)

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site that this subnet is deployed from.

inline_devices optional Array

An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [
       1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps subnet My first Subnet!.",
     "status_code": 422
   }
 }

IPAM - Create a new supernet

Create a new supernet. A supernet is a top level subnet (all of your defined subnets are contained within a supernet.) For example, if you want to define the subnet 10.0.0.0/24 to use in your network, you would want to define a supernet at least as large as that in order to contain it.

https://example.sonar.software/api/v1/network/ipam/supernets

Parameter

Field Type Description
name String

A descriptive name for the supernet

subnet String

The network address and CIDR prefix (e.g. 10.0.0.0/8)

Success 200

Field Type Description
id Number

The internal id of the supernet

name String

A descriptive name for the supernet

subnet String

The supernet network address and CIDR prefix.

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "My second SUPERNET!",
    "subnet": "172.16.0.0/23"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "Your submission overlaps supernet My first SUPERNET!.",
     "status_code": 422
   }
 }

IPAM - Delete IP pool

Delete an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Integer

The ID of the supernet

subnet_id Integer

The ID of the subnet

ip_pool_id Integer

The ID of the IP pool

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name Type Description
message String

A reason as to why the IP pool could not be deleted

status_code Integer

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete a pool that contains IP assignments."
         },
         "status_code": 422
     }
 }

IPAM - Delete IP pool

Delete an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

ip_pool_id Number

The ID of the IP pool

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name Type Description
message String

A reason as to why the IP pool could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "You cannot delete a pool that contains IP assignments."
         },
         "status_code": 422
     }
 }

IPAM - Delete subnet

Delete a subnet. You cannot delete a subnet that has any IP pools or IP assignments associated with it, the relations must be deleted first.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field Type Description
id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name Type Description
message String

A reason as to why the subnet could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "This subnet cannot be deleted as it has IP pools associated with it."
         },
         "status_code": 422
     }
 }

IPAM - Delete supernet

Delete a supernet. You cannot delete a supernet that has any subnets associated with it, the subnets must be deleted first.

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field Type Description
id Number

The ID of the supernet

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
}

Error 4xx

Name Type Description
message String

A reason as to why the supernet could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "Supernet cannot be deleted as it contains subnets."
         },
         "status_code": 422
     }
 }

IPAM - Get all IP pools

Get a list of IP pools contained within a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field Type Description
supernet_id Integer

The ID of the supernet

subnet_id Integer

The ID of the subnet

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

dhcp_server_identifier_id Integer

The DHCP server identifier used for this pool. Will be null if unset.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first IP Pool",
      "start": "192.168.100.10",
      "end": "192.168.100.200",
      "dhcp_servers": [
           1,
           2
      ],
      "dhcp_server_identifier_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all IP pools

Get a list of IP pools contained within a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools

Parameter

Field Type Description
supernet_id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first IP Pool",
      "start": "192.168.100.10",
      "end": "192.168.100.200",
      "dhcp_servers": [
           1,
           2
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all subnets

Get a list of subnets contained within a supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field Type Description
id Number

The ID of the supernet

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

poller_id Number

The ID of the poller responsible for this subnet

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first Subnet!",
      "subnet": "192.168.100.0/27",
      "type": "customer",
      "network_site_id": 1,
      "supernet_id": 4,
      "inline_devices": [
           1
       ],
       "poller_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all subnets

Get a list of subnets contained within a supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets

Parameter

Field Type Description
id Number

The ID of the supernet

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My first Subnet!",
      "subnet": "192.168.100.0/27",
      "type": "customer",
      "network_site_id": 1,
      "supernet_id": 4,
      "inline_devices": [
           1
       ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get all supernets

Get a list of supernets. A supernet is a top level subnet (all of your defined subnets are contained within a supernet.) For example, if you want to define the subnet 10.0.0.0/24 to use in your network, you would want to define a supernet at least as large as that in order to contain it.

https://example.sonar.software/api/v1/network/ipam/supernets

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the supernet

name String

A descriptive name for the supernet

subnet String

The supernet network address and CIDR prefix.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 4,
      "name": "My first IPv6 Supernet!",
      "subnet": "2001::/48"
    },
    {
      "id": 5,
      "name": "My Second Supernet",
      "subnet": "10.0.0.0/8"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

IPAM - Get individual IP pool

Get an individual IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Integer

The ID of the supernet

subnet_id Integer

The ID of the subnet

ip_pool_id Integer

The ID of the IP pool

Success 200

Field Type Description
id Integer

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

dhcp_server_identifier_id Integer

The DHCP server identifier used for this pool. Will be null if unset.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
       1,
       2
     ],
     "dhcp_server_identifier_id": 1
  }
}

IPAM - Get individual IP pool

Get an individual IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnet/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

ip_pool_id Number

The ID of the IP pool

Success 200

Field Type Description
id Number

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.21",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

IPAM - Get individual subnet

Get an individual subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field Type Description
id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

poller_id Number

The ID of the poller responsible for this subnet

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [],
    "poller_id": 12
  }
}

IPAM - Get individual subnet

Get an individual subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnet/:subnet_id

Parameter

Field Type Description
id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet!",
    "subnet": "192.168.100.0/27",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": []
  }
}

IPAM - Get individual supernet

Get an individual supernet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field Type Description
id Number

The ID of the supernet

Success 200

Field Type Description
id Number

The internal id of the supernet

name String

A descriptive name for the supernet

subnet String

The supernet network address and CIDR prefix.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My Second Supernet",
    "subnet": "10.0.0.0/8"
  }
}

IPAM - Update IP pool

Update an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Integer

The ID of the supernet

subnet_id Integer

The ID of the subnet

ip_pool_id Integer

The ID of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

dhcp_server_identifier_id Integer

The ID of a DHCP server identifier to use for this pool. Set to null to use no identifier.

Success 200

Field Type Description
id Integer

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

dhcp_server_identifier_id Integer

The DHCP server identifier used for this pool. Will be null if unset.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.24",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
     ],
     "dhcp_server_identifier_id": 4
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Pool cannot be set to dynamic, as there are existing assignments in the space this pool is attempting to occupy."
         },
         "status_code": 422
     }
 }

IPAM - Update IP pool

Update an IP pool.

https://example.sonar.software/api/v1/network/ipam/supernets/:supernet_id/subnets/:subnet_id/ip_pools/:ip_pool_id

Parameter

Field Type Description
supernet_id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

ip_pool_id Number

The ID of the IP pool

name optional String

A descriptive name for the IP pool

start optional String

The starting IP for the IP pool

end optional String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any IDs included here that have 'control_all_pools' set to true will cause the call to fail.

Success 200

Field Type Description
id Number

The internal id of the IP pool

name String

A descriptive name for the IP pool

start String

The starting IP for the IP pool

end String

The ending IP for the IP pool

dhcp_servers Array

An array of DHCP server IDs. These are DHCP servers that are not set to control all pools and are specifically associated with this IP pool. Any DHCP server that has 'control_all_pools' set to true will also provide DHCP for this pool, but will not be shown here.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My first IP pool",
    "start": "192.168.100.24",
    "end": "192.168.100.25",
    "dhcp_servers": [
           1,
           2
      ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Pool cannot be set to dynamic, as there are existing assignments in the space this pool is attempting to occupy."
         },
         "status_code": 422
     }
 }

IPAM - Update a dynamic IP assignment

This endpoint is deprecated and should not be used. Please visit https://github.com/sonarsoftware/dhcp_batcher for information on our new dynamic DHCP tool.

This can be submitted as either a GET or a POST, to accomodate different hardware. The sole intent of this endpoint is to tie in an external IP assignment system (e.g. a third party DHCP server) so that it can notify Sonar of lease assignment and expiration. Sonar will then use this data to perform actions such as updating an address list on a gateway device. Using this as a GET may cause issues with things like submitting JSON for the 'reference' attribute unless you implement URL encoding - using POST is always recommended if possible! An example of an automated script that can be used on a Mikrotik to deliver leases to Sonar is below.

#Set your Sonar information directly below
:global username "admin"
:global password "sonar"
:global url "192.168.1.23"

:if ($leaseBound = 0) do={ /tool fetch url="https://$url/api/v1/network/ipam/dynamic_ip_assignment?ip_address=$leaseActIP&mac_address=$leaseActMAC&expired=1" mode=https keep-result=no user=$username password=$password } else={ /tool fetch url="https://$url/api/v1/network/ipam/dynamic_ip_assignment?ip_address=$leaseActIP&mac_address=$leaseActMAC&expired=0" mode=https keep-result=no user=$username password=$password }

The criteria checked when an assignment is incoming is as follows.

  • Does a pool exist that this IP fits into?
  • Is this IP already assigned as a static assignment?
  • Does the MAC address exist as a MAC field on a piece of inventory assigned to an account?
If any of these checks are false, then the IP assignment will not be stored.

https://example.sonar.software/api/v1/network/ipam/dynamic_ip_assignment

Parameter

Field Type Description
expired optional Boolean

If this submission is notify that is a lease is expiring, set this to true.

Default value: false

ip_address String

The IP address that is being assigned. You can also submit this as a subnet with a CIDR prefix if this is a larger assignment. While this will accept both IPv4 and IPv6, you would need some external method of figuring out a link between the IPv6 address and a MAC for association within Sonar, so this is likely to be difficult.

mac_address String

The MAC address this IP is assigned to, in XX:XX:XX:XX:XX:XX format. The MAC submitted here should be the MAC you want Sonar to search for in order to find a match, so this does not necessarily need to be the 'real' MAC, but could instead be the MAC of the CPE or something similar.

reference optional String

If you would like to store additional information about this assignment for display in Sonar, submit it here as JSON. Sonar will parse the JSON to use for later display. For example, if you wanted to submit the hostname for the reservation, send something like { "Hostname": "Alex's Laptop" }

Success 200

Field Type Description
account_id Number

The ID of the account that this is linked to. Will be null if no match was found.

ip_address String

The IP address that is being assigned.

assigned_time String

The time the lease was assigned in UTC.

expired_time String

The time the lease expired in UTC, will be null if it is still active.

HTTP/1.1 200 OK
{
  "data": {
    "account_id": 5,
    "ip_address": "192.168.100.12",
    "assigned_time": "2016-01-01 12:34:45",
    "expired_time": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "ip_address": "Invalid IP address."
         },
         "status_code": 422
     }
 }

IPAM - Update subnet

Update a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field Type Description
id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

name optional String

A descriptive name for the subnet.

subnet optional String

The network address and CIDR prefix (e.g. 10.0.0.0/8)

type optional String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id optional Number

The ID of the network site that this subnet is deployed from.

inline_devices optional Array

An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

poller_id optional Number

The ID of the poller responsible for this subnet

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

poller_id Number

The ID of the poller responsible for this subnet

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet Redux",
    "subnet": "192.168.100.0/28",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": [],
    "poller_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing IP pools linked to this subnet."
         },
         "status_code": 422
     }
 }

IPAM - Update subnet

Update a subnet.

https://example.sonar.software/api/v1/network/ipam/supernets/:id/subnets/:subnet_id

Parameter

Field Type Description
id Number

The ID of the supernet

subnet_id Number

The ID of the subnet

name optional String

A descriptive name for the subnet.

subnet optional String

The network address and CIDR prefix (e.g. 10.0.0.0/8)

type optional String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id optional Number

The ID of the network site that this subnet is deployed from.

inline_devices optional Array

An array of inline device IDs that should provide controls for this subnet. You can only submit IDs here for inline devices that do not have the 'Controls all subnets' value enabled.

Success 200

Field Type Description
id Number

The internal id of the subnet

name String

A descriptive name for the subnet

subnet String

The subnet network address and CIDR prefix.

type String

The type of subnet this is.

Allowed values: "customer", "infrastructure", "reserved", "mixed"

network_site_id Number

The ID of the network site this subnet is associated with.

supernet_id Number

The ID of the supernet that this subnet is contained in.

inline_devices Array

A list of inline device IDs that control this subnet.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "My first Subnet Redux",
    "subnet": "192.168.100.0/28",
    "type": "customer",
    "network_site_id": 1,
    "supernet_id": 4,
    "inline_devices": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing IP pools linked to this subnet."
         },
         "status_code": 422
     }
 }

IPAM - Update supernet

Update a supernet

https://example.sonar.software/api/v1/network/ipam/supernets/:id

Parameter

Field Type Description
id Number

The ID of the supernet

name String

The name of the supernet

subnet String

The supernet network address and CIDR prefix.

Success 200

Field Type Description
id Number

The internal id of the supernet

name optional String

A descriptive name for the supernet

subnet optional String

The supernet network address and CIDR prefix.

HTTP/1.1 200 OK
{
  "data": {
    "id": 5,
    "name": "My Second Supernet",
    "subnet": "10.0.0.0/8"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "Your new subnet is too small to contain all existing subnets linked to this supernet."
         },
         "status_code": 422
     }
 }

Inbound Email Accounts

Inbound_Email_Accounts - Create a new inbound email account

Create a new inbound email account.

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts

Parameter

Field Type Description
name String

A descriptive name for the inbound email account

reply_address String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name String

The name that emails sent using this account will be sent from.

enabled optional Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

Default value: true

user_id optional Number

The ID of a user that will be the responsible user for tickets created using this inbound route. You must set either a user ID or a ticket group ID.

ticket_group_id optional Number

The ID of a ticket group that tickets created using this inbound route should be placed into. You must set either a user ID or a ticket group ID.

priority optional Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Default value: 4

Allowed values: 1, 2, 3, 4

reply optional String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature optional String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering optional Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

Default value: false

minimum_spam_score optional Number

The minimum spam score for an inbound email to be considered spam.

Default value: 5

days_before_spam_deletion optional Number

The number of days for spam to remain in the spam folder before being automatically deleted.

Default value: 30

slack_enabled optional Boolean

Enable Slack.com integration

Default value: false

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration, required if slack_enabled is true

Success 200

Field Type Description
id Number

The ID of the inbound email account.

name String

A descriptive name for the inbound email account

reply_address String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name String

The name that emails sent using this account will be sent from.

mailbox String

The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.

enabled Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

user_id Number

The ID of a user that will be the responsible user for tickets created using this inbound route.

ticket_group_id Number

The ID of a ticket group that tickets created using this inbound route should be placed into.

priority Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Allowed values: 1, 2, 3, 4

reply String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

minimum_spam_score Number

The minimum spam score for an inbound email to be considered spam.

days_before_spam_deletion Number

The number of days for spam to remain in the spam folder before being automatically deleted.

slack_enabled optional Boolean

Slack.com integration status

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "name": "Technical Support Tier 3",
    "reply_address": "support@sonar.software",
    "reply_name": "Charles Darwin",
    "mailbox": "another_example_ok@sonarticketing.rocks",
    "enabled": true,
    "user_id": 1,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Inbound_Email_Accounts - Delete an inbound email account

Delete a inbound email account

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field Type Description
id Number

The ID of the inbound email account

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the inbound email account could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Inbound email account does not exist.",
         "status_code": 404
     }
 }

Inbound_Email_Accounts - Get all inbound email accounts

Get all inbound email accounts

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inbound email account.

name String

A descriptive name for the inbound email account

reply_address String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name String

The name that emails sent using this account will be sent from.

mailbox String

The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.

enabled Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

user_id Number

The ID of a user that will be the responsible user for tickets created using this inbound route.

ticket_group_id Number

The ID of a ticket group that tickets created using this inbound route should be placed into.

priority Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Allowed values: 1, 2, 3, 4

reply String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

minimum_spam_score Number

The minimum spam score for an inbound email to be considered spam.

days_before_spam_deletion Number

The number of days for spam to remain in the spam folder before being automatically deleted.

slack_enabled optional Boolean

Slack.com integration status

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Sales",
      "reply_address": "sales@sonar.software",
      "reply_name": "Sonar",
      "mailbox": "example@sonarticketing.rocks",
      "enabled": true,
      "user_id": null,
      "ticket_group_id": null,
      "priority": 4,
      "reply": "

Thanks for emailing us, pal!

", "signature": null, "automatic_spam_filtering": false, "minimum_spam_score": 12, "days_before_spam_deletion": 60, "slack_enabled": false, "slack_webhook_url": null }, { "id": 3, "name": "Test with reply", "reply_address": "simon-test@sonar.software", "reply_name": "Sir Chumley", "mailbox": "another_example@sonarticketing.rocks", "enabled": true, "user_id": null, "ticket_group_id": 4, "priority": 2, "reply": "This is my reply if you don't like it, you can always replace it!", "signature": "[PUBLIC_NAME]
Kings of the jungle.", "automatic_spam_filtering": false, "minimum_spam_score": 12, "days_before_spam_deletion": 60, "slack_enabled": false, "slack_webhook_url": null } ], "paginator": { "total_count": 2, "total_pages": 1, "current_page": 1, "limit": 100 } }

Inbound_Email_Accounts - Get an individual inbound email account

Get an individual inbound email account

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field Type Description
id Number

The ID of the inbound email account

Success 200

Field Type Description
id Number

The ID of the inbound email account.

name String

A descriptive name for the inbound email account

reply_address String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name String

The name that emails sent using this account will be sent from.

mailbox String

The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.

enabled Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

user_id Number

The ID of a user that will be the responsible user for tickets created using this inbound route.

ticket_group_id Number

The ID of a ticket group that tickets created using this inbound route should be placed into.

priority Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Allowed values: 1, 2, 3, 4

reply String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

minimum_spam_score Number

The minimum spam score for an inbound email to be considered spam.

days_before_spam_deletion Number

The number of days for spam to remain in the spam folder before being automatically deleted.

slack_enabled optional Boolean

Slack.com integration status

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Sales",
    "reply_address": "sales@sonar.software",
    "reply_name": "Sonar",
    "mailbox": "example@sonarticketing.rocks",
    "enabled": true,
    "user_id": null,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inbound_Email_Accounts - Update inbound email account

Update an existing inbound email account.

https://example.sonar.software/api/v1/system/tickets/inbound_email_accounts/:id

Parameter

Field Type Description
id Number

The inbound email account ID

name optional String

A descriptive name for the inbound email account

reply_address optional String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name optional String

The name that emails sent using this account will be sent from.

enabled optional Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

user_id optional Number

The ID of a user that will be the responsible user for tickets created using this inbound route. You must set either a user ID or a ticket group ID.

ticket_group_id optional Number

The ID of a ticket group that tickets created using this inbound route should be placed into. You must set either a user ID or a ticket group ID.

priority optional Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Allowed values: 1, 2, 3, 4

reply optional String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature optional String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering optional Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

Default value: false

minimum_spam_score optional Number

The minimum spam score for an inbound email to be considered spam.

Default value: 5

days_before_spam_deletion optional Number

The number of days for spam to remain in the spam folder before being automatically deleted.

Default value: 30

slack_enabled optional Boolean

Enable Slack.com integration

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration, required if slack_enabled is true

Success 200

Field Type Description
id Number

The ID of the inbound email account.

name String

A descriptive name for the inbound email account

reply_address String

The email address that emails sent using this account will be sent from, and wil have as a reply to address.

reply_name String

The name that emails sent using this account will be sent from.

mailbox String

The mailbox at sonarticketing.rocks that you should forward email to in order for it to be delivered to Sonar.

enabled Boolean

Whether the account is enabled. Disabled accounts will not accept inbound email.

user_id Number

The ID of a user that will be the responsible user for tickets created using this inbound route.

ticket_group_id Number

The ID of a ticket group that tickets created using this inbound route should be placed into.

priority Number

The priority of tickets created using this inbound route. 1 = critical, 2 = high, 3 = medium, 4 = low

Allowed values: 1, 2, 3, 4

reply String

The automatic reply to emails sent to this inbound route. Can use some basic HTML.

signature String

The signature appended to emails sent using this account. One variable is allowed in the signature which is [PUBLIC_NAME], this variable will be replaced with the user's public name.

automatic_spam_filtering Boolean

Whether or not to enable automatic spam filtering for this inbound account. Spam filtering uses SpamAssassin.

minimum_spam_score Number

The minimum spam score for an inbound email to be considered spam.

days_before_spam_deletion Number

The number of days for spam to remain in the spam folder before being automatically deleted.

slack_enabled optional Boolean

Slack.com integration status

slack_webhook_url optional String

The Slack webhook URL to use for Slack integration

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Technical Support Tier 1000",
    "reply_address": "sales@sonar.software",
    "reply_name": "Sonar",
    "mailbox": "some_real_good_example@sonarticketing.rocks",
    "enabled": true,
    "user_id": 2,
    "ticket_group_id": null,
    "priority": 4,
    "reply": null,
    "signature": null,
    "automatic_spam_filtering": false,
    "minimum_spam_score": 12,
    "days_before_spam_deletion": 60,
    "slack_enabled": false,
    "slack_webhook_url": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inline Devices

Inline_Devices - Get all inline devices

Get a list of inline devices.

https://example.sonar.software/api/v1/network/provisioning/inline_devices

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inline device

name String

The name provided for the inline device

ip_address String

The IP address of the inline device

type String

The type of inline device that this is

Allowed values: "mikrotik", "proceraPacketLogic"

all_subnets Boolean

If this inline device writes address list entries for every subnet in Sonar, this will be true

enabled Boolean

If this is false, no address list entries will be written

device_status Boolean

Whether or not the device is in a good status. Devices with a status of 'false' will not have address list entries written.

status_message String

A message describing why the device is in a bad status, if device_status is false.

failures Number

The number of failures writing address list entries that have been encountered since last rewrite/reset

subnets Array

If all_subnets is false, this will be an array of subnet ID that the device writes address list entries for.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "My Awesome RB2011",
      "type": "mikrotik",
      "ip_address": "192.168.1.51",
      "all_subnets": true,
      "enabled": true,
      "device_status": true,
      "status_message": false,
      "failures": 4,
      "subnets": []
    },
    {
      "id": 1,
      "name": "7810",
      "type": "proceraPacketLogic",
      "ip_address": "192.168.1.240",
      "all_subnets": true,
      "enabled": true,
      "device_status": true,
      "status_message": false,
      "failures": 2,
      "subnets": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inline_Devices - Get individual inline device

Get a single inline device

https://example.sonar.software/api/v1/network/provisioning/inline_devices/:id

Parameter

Field Type Description
id Number

The ID of the inline device

Success 200

Field Type Description
id Number

The ID of the inline device

name String

The name provided for the inline device

ip_address String

The IP address of the inline device

type String

The type of inline device that this is

Allowed values: "mikrotik", "proceraPacketLogic"

all_subnets Boolean

If this inline device writes address list entries for every subnet in Sonar, this will be true

enabled Boolean

If this is false, no address list entries will be written

device_status Boolean

Whether or not the device is in a good status. Devices with a status of 'false' will not have address list entries written.

status_message String

A message describing why the device is in a bad status, if device_status is false.

failures Number

The number of failures writing address list entries that have been encountered since last rewrite/reset

subnets Array

If all_subnets is false, this will be an array of subnet ID that the device writes address list entries for.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "7810",
    "type": "proceraPacketLogic",
    "ip_address": "192.168.1.240",
    "all_subnets": true,
    "enabled": true,
    "device_status": true,
    "status_message": false,
    "failures": 2,
    "subnets": []
  }
}

Inventory Assignees

Inventory_Assignees - Create a new generic inventory assignee

Create a new generic inventory assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees

Parameter

Field Type Description
name String

A unique name for the assignee

notes optional String

Some notes to describe the assignee

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

notes String

Some notes to describe the assignee

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Mike's House of Installs",
    "notes": "If you give routers to Mike, put them here!"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Create a new location

Create a new physical inventory location.

https://example.sonar.software/api/v1/inventory/inventory_locations

Parameter

Field Type Description
name String

A unique name for the location

Success 200

Field Type Description
id Number

The internal id of the location

name String

The name of the location

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "name": "Warehouse 4A-B6-234"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Create a new vehicle

Create a new vehicle. Vehicles are a type of location inventory can be stored in.

https://example.sonar.software/api/v1/inventory/vehicles

Parameter

Field Type Description
name String

The unique name of the vehicle

manufacturer optional String

The vehicle manufacturer

model optional String

The vehicle model

year optional Number

The year the vehicle was constructed

license_plate optional String

The license plate/number plate of the vehicle

vin optional String

The VIN (vehicle identification number) of the vehicle

Success 200

Field Type Description
id Number

The internal id of the vehicle

name String

The name of the vehicle

manufacturer String

The vehicle manufacturer

model String

The vehicle model

year Number

The year the vehicle was constructed

license_plate String

The license plate/number plate of the vehicle

vin String

The VIN (vehicle identification number) of the vehicle

HTTP/1.1 201 OK
{
    "data": {
          "id": 1,
          "name": "Bob's Work Van",
          "manufacturer": "Fjord",
          "model": "G150",
          "year": 2014,
          "license_plate": "ABC123",
          "vin": "1231231234"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Delete generic inventory assignee

Delete a generic inventory assignee

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field Type Description
id Number

The ID of the generic inventory assignee

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the generic inventory assignee could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Assignee cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Delete location

Delete an inventory location

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field Type Description
id Number

The ID of the location

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the location could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Location cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Delete vehicle

Delete a vehicle

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field Type Description
id Number

The ID of the vehicle

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the vehicle could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Vehicle cannot be deleted as inventory items are stored in it.",
         "status_code": 422
     }
 }

Inventory_Assignees - Get all generic inventory assignees

Get a list of generic inventory assignees. A generic inventory assignee is used when nothing else matches - for example, you may use this to assign inventory to contractors.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

notes String

Some notes to describe the assignee

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Jim's Sloppy Contracting Service",
      "notes": "This is the place to assign inventory that we give to this contractor!"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Assignees - Get all locations

Get a list of physical locations that inventory items can be stored at.

https://example.sonar.software/api/v1/inventory/inventory_locations

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the location

name String

The name of the location

HTTP/1.1 200 OK
{
    "data": [
       {
            "id": 35,
            "name": "Benjamin's Big Red Barn"
       },
       {
           "id": 36,
           "name": "Main Warehouse"
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Assignees - Get all vehicles

Get a list of vehicles. Vehicles are a type of location inventory can be stored in.

https://example.sonar.software/api/v1/inventory/vehicles

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the vehicle

name String

The name of the vehicle

manufacturer String

The vehicle manufacturer

model String

The vehicle model

year Number

The year the vehicle was constructed

license_plate String

The license plate/number plate of the vehicle

vin String

The VIN (vehicle identification number) of the vehicle

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Bob's Work Van",
      "manufacturer": "Fjord",
      "model": "G150",
      "year": 2014,
      "license_plate": "ABC123",
      "vin": "1231231234"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Assignees - Get individual generic inventory assignee

Get an individual generic assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field Type Description
id Number

The ID of the assignee

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

notes String

Some notes to describe the assignee

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Mike's House of Installs",
    "notes": "If you give routers to Mike, put them here!"
  }
}

Inventory_Assignees - Get individual location

Get an individual physical inventory location.

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field Type Description
id Number

The ID of the location

Success 200

Field Type Description
id Number

The internal id of the location

name String

The name of the location

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Warehouse"
   }
}

Inventory_Assignees - Get individual vehicle

Get an individual vehicle.

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field Type Description
id Number

The ID of the vehicle

Success 200

Field Type Description
id Number

The internal id of the vehicle

name String

The name of the vehicle

manufacturer String

The vehicle manufacturer

model String

The vehicle model

year Number

The year the vehicle was constructed

license_plate String

The license plate/number plate of the vehicle

vin String

The VIN (vehicle identification number) of the vehicle

HTTP/1.1 200 OK
{
  "data": {
        "id": 1,
        "name": "Bob's Work Van",
        "manufacturer": "Fjord",
        "model": "G150",
        "year": 2014,
        "license_plate": "ABC123",
        "vin": "1231231234"
  }
}

Inventory_Assignees - Update generic inventory assignee

Update a generic inventory assignee.

https://example.sonar.software/api/v1/inventory/generic_inventory_assignees/:id

Parameter

Field Type Description
id Number

The ID of the assignee

name optional String

A unique name for the assignee

notes optional String

Some notes to describe the assignee

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

notes String

Some notes to describe the assignee

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Michael's House of Installs",
    "notes": "If you give routers to Mike, put them here! Don't call him Mike."
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Update location

Update a physical inventory location

https://example.sonar.software/api/v1/inventory/inventory_locations/:id

Parameter

Field Type Description
id Number

The ID of the location

name String

The name of the location

Success 200

Field Type Description
id Number

The internal id of the location

name String

The name of the location

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Not the Warehouse"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Assignees - Update vehicle

Update a vehicle

https://example.sonar.software/api/v1/inventory/vehicles/:id

Parameter

Field Type Description
id Number

The ID of the vehicle

name optional String

The unique name of the vehicle

manufacturer optional String

The vehicle manufacturer

model optional String

The vehicle model

year optional Number

The year the vehicle was constructed

license_plate optional String

The license plate/number plate of the vehicle

vin optional String

The VIN (vehicle identification number) of the vehicle

Success 200

Field Type Description
id Number

The internal id of the vehicle

name String

The name of the vehicle

manufacturer String

The vehicle manufacturer

model String

The vehicle model

year Number

The year the vehicle was constructed

license_plate String

The license plate/number plate of the vehicle

vin String

The VIN (vehicle identification number) of the vehicle

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Bill's Work Van",
    "manufacturer": "Dadge",
    "model": "Rum",
    "year": "2014",
    "license_plate": "ABC123",
    "vin": "1231231234"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory Depletion Thresholds

Inventory_Depletion_Thresholds - Create a new depletion threshold

Create a new depletion threshold.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds

Parameter

Field Type Description
enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success 200

Field Type Description
id Number

The internal ID of the threshold

enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "enabled": true,
    "threshold": 100,
    "type": "aggregate",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [],
    "included_inventory_location_ids": [],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "notified_user_ids": "At least one user ID is not a valid user ID.",
         },
         "status_code": 422
     }
 }

Inventory_Depletion_Thresholds - Delete depletion threshold

Delete a manufacturer

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field Type Description
id Number

The ID of the depletion threshold

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the depletion threshold could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID could be found.",
         "status_code": 404
     }
 }

Inventory_Depletion_Thresholds - Get all depletion thresholds

Get a list of depletion thresholds for this model ID. A depletion threshold allows you to define criteria by which a group of users are notified when the quantity of items for a specific model falls below a certain threshold. This can also be constrained by specific assignees - for example, you can be notified when there are less than 50 widgets in your 'Main Warehouse' and less than 100 widgets across all inventory locations.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

model_id Number

The internal ID of the inventory model

Success 200

Field Type Description
id Number

The internal ID of the threshold

enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 2,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 3,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 4,
      "enabled": true,
      "threshold": 100,
      "type": "aggregate",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [
        1
      ],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    },
    {
      "id": 5,
      "enabled": true,
      "threshold": 100,
      "type": "single",
      "include_inventory_locations": true,
      "include_vehicles": false,
      "include_generic_inventory_assignees": false,
      "notified_user_ids": [
        1
      ],
      "included_inventory_location_ids": [
        1
      ],
      "included_vehicle_ids": [],
      "included_generic_inventory_assignee_ids": []
    }
  ],
  "paginator": {
    "total_count": 5,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Depletion_Thresholds - Get individual depletion threshold

Get an individual depletion threshold from a single model.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field Type Description
model_id Number

The ID of an inventory model

depletion_threshold_id Number

The ID of a depletion threshold

Success 200

Field Type Description
id Number

The internal ID of the threshold

enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 1,
    "enabled": true,
    "threshold": 100,
    "type": "aggregate",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [],
    "included_inventory_location_ids": [],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Inventory_Depletion_Thresholds - Update depletion threshold

Update a depletion threshold.

https://example.sonar.software/api/v1/inventory/models/:model_id/depletion_thresholds/:depletion_threshold_id

Parameter

Field Type Description
model_id Number

The ID of the inventory model

depletion_threshold_id Number

The ID of the depletion threshold

enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

Success 200

Field Type Description
id Number

The internal ID of the threshold

enabled Boolean

Whether or not the threshold is enabled. Disabled thresholds will not send alerts

threshold Number

The quantity of items below which the threshold is triggered

type String

The type of threshold. An aggregate threshold is applied to all assignees, constrained by the boolean values described below. A single threshold is applied individually to each assignee defined within the assignee arrays defined below.

Allowed values: "aggregate", "single"

include_inventory_locations Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all inventory locations

include_vehicles Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all vehicles

include_generic_inventory_assignees Boolean

If this is true and type is aggregate, then this threshold will be applied to all models of this ID across all generic inventory assignees

notified_user_ids Array

An array of user IDs that are notified when this threshold is violated

included_inventory_location_ids Array

If type is single, the array of IDs in here correspond to inventory locations that this threshold is applied to

included_vehicle_ids Array

If type is single, the array of IDs in here correspond to vehicles that this threshold is applied to

included_generic_inventory_assignee_ids Array

If type is single, the array of IDs in here correspond to generic inventory assignees that this threshold is applied to

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "enabled": true,
    "threshold": 50,
    "type": "single",
    "include_inventory_locations": true,
    "include_vehicles": false,
    "include_generic_inventory_assignees": false,
    "notified_user_ids": [
      1
    ],
    "included_inventory_location_ids": [
      1
    ],
    "included_vehicle_ids": [],
    "included_generic_inventory_assignee_ids": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "notified_user_ids": "One of the IDs in notified_user_ids is invalid."
         },
         "status_code": 422
     }
 }

Inventory Items

Inventory_Items - Create a new inventory model deployment type

Create a new inventory model deployment type.

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types

Parameter

Field Type Description
inventory_model_id Integer

The ID of the inventory model to create the type for

deployment_type String

A descriptive name for the inventory model deployment type

Success 200

Field Type Description
id Integer

The ID of the inventory model deployment type.

deployment_type String

The name of the inventory model deployment type

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Inventory_Items - Create a new manufacturer

Create a new manufacturer.

https://example.sonar.software/api/v1/inventory/manufacturers

Parameter

Field Type Description
name String

A unique name for the manufacturer

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "name": "Cambium"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model field

Create a new model field.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field Type Description
id Number

The ID of the model

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required optional Boolean

Whether or not the field is required to be completed when entering a new inventory item. If you do not add any fields, the item will be treated as generic, and can be added and reassigned by quantity. If an item has fields, is is unique and must always be referenced directly when adding and reassigning

Default value: true

unique optional Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

Default value: false

regexp optional String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field Type Description
name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name is required.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model field

Create a new model field.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field Type Description
id Number

The ID of the model

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required optional Boolean

Whether or not the field is required to be completed when entering a new inventory item. If you do not add any fields, the item will be treated as generic, and can be added and reassigned by quantity. If an item has fields, is is unique and must always be referenced directly when adding and reassigning

Default value: true

unique optional Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

Default value: false

regexp optional String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field Type Description
name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name is required.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model

Create a new model.

https://example.sonar.software/api/v1/inventory/models

Parameter

Field Type Description
manufacturer_id Number

The internal id of the manufacturer

name String

The name of the model

inventory_model_category_id Number

The category ID that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

HTTP/1.1 201 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": true,
       "port": 443
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create a new model

Create a new model.

https://example.sonar.software/api/v1/inventory/models

Parameter

Field Type Description
manufacturer_id Number

The internal id of the manufacturer

name String

The name of the model

inventory_model_category_id Number

The category ID that this model is part of

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

HTTP/1.1 201 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create category

Create an inventory model category. This describes a group of inventory models and should be descriptive enough to be utilized in provisioning, monitoring, etc. For example, 'CPE Routers', 'CPE Radios' or 'GPON ONTs' is typically sufficiently descriptive but 'CPE' would not be.

https://example.sonar.software/api/v1/inventory/categories

Parameter

Field Type Description
name String

The name of the category

Success 200

Field Type Description
id Number

The ID of the category

name String

The name of the category

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name must be unique.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create inventory items

Create inventory items. This endpoint is slightly different than other endpoints as you must submit data in an array. This allows you to save multiple items at a time. It is recommended that you do validation on the input fields before submitting them here, as if you are submitting a large amount of items, a single invalid field will abort the entire insertion. If you are inserting very large quantities of items (1000) then make sure you set an adequate timeout on your connection, as it may take some additional time to process the data. You can also batch the insertions into groups in order to speed up processing.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field Type Description
model_id Number

The ID of an inventory model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

condition optional String

The condition of the items

Default value: new

Allowed values: "new", "used"

individualList optional Array

An array of field objects, if items being added have fields. The format of the field object is a 'fields' property, which is an object with multiple properties representing field IDs, and values representing field data. See example below. If there are no fields defined and you are entering multiple generic items, use the 'quantity' option show below.

quantity optional Number

Only valid if the item being added has no fields defined. You must either define quantity or individualList.

purchase_price optional Number

Set the purchase price for the items, in your local currency. This is used for reporting purposes.

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "condition": "new",
    "individualList": [
        {
            "fields": {
                "1228": "This is the data for field ID 1228",
                "1229": "This is the data for field ID 1229"
            }
        },
        {
            "fields": {
                "1228": "This is the data for a second item being inserted for field ID 1228",
                "1229": "This is the data for a second item being inserted for field ID 1229"
            }
        }
    ]
}
{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "quantity": 15
}

Success 200

Field Type Description
ids Array

An array of inventory item IDs that have been created by this import

HTTP/1.1 201 OK
{
  "data": {
    "ids": [
       1,
       2,
       3,
       4
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Create inventory items

Create inventory items. This endpoint is slightly different than other endpoints as you must submit data in an array. This allows you to save multiple items at a time. It is recommended that you do validation on the input fields before submitting them here, as if you are submitting a large amount of items, a single invalid field will abort the entire insertion. If you are inserting very large quantities of items (1000) then make sure you set an adequate timeout on your connection, as it may take some additional time to process the data. You can also batch the insertions into groups in order to speed up processing.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field Type Description
model_id Number

The ID of an inventory model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

condition optional String

The condition of the items

Default value: new

Allowed values: "new", "used"

individualList optional Array

An array of field objects, if items being added have fields. The format of the field object is a 'fields' property, which is an object with multiple properties representing field IDs, and values representing field data. See example below. If there are no fields defined and you are entering multiple generic items, use the 'quantity' option show below.

quantity optional Number

Only valid if the item being added has no fields defined. You must either define quantity or individualList.

purchase_price optional Number

Set the purchase price for the items, in your local currency. This is used for reporting purposes.

{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "condition": "new",
    "individualList": [
        {
            "fields": {
                "1228": "This is the data for field ID 1228",
                "1229": "This is the data for field ID 1229"
            }
        },
        {
            "fields": {
                "1228": "This is the data for a second item being inserted for field ID 1228",
                "1229": "This is the data for a second item being inserted for field ID 1229"
            }
        }
    ]
}
{
    "assignee_type": "generic_inventory_assignees",
    "assignee_id": 23,
    "model_id": 1305,
    "quantity": 15
}

Success 200

Field Type Description
ids Array

An array of inventory item IDs that have been created by this import

HTTP/1.1 201 OK
{
  "data": {
    "ids": [
       1,
       2,
       3,
       4
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Delete a inventory model deployment type

Delete a inventory model deployment type

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field Type Description
inventory_model_id Integer

The ID of the inventory model to delete the type from

id Integer

The ID of the inventory model deployment type

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the inventory model deployment type could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "inventory model deployment type does not exist.",
         "status_code": 404
     }
 }

Inventory_Items - Delete category

Delete an inventory model category

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field Type Description
id Number

The ID of the category

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the category could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Category cannot be deleted as inventory models are utilizing it.",
         "status_code": 422
     }
 }

Inventory_Items - Delete item

Delete an item. Generally, you don't want to do this unless you've made a mistake. If a unit is failed or sold, you should use the appropriate properties to denote that. Deleting items from inventory will destroy history.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the item

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the item could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Item cannot be deleted as it has been sold.",
         "status_code": 422
     }
 }

Inventory_Items - Delete manufacturer

Delete a manufacturer

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field Type Description
id Number

The ID of the manufacturer

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the manufacturer could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Manufacturer cannot be deleted as inventory models are utilizing it."
         "status_code": 422
     }
 }

Inventory_Items - Delete model field

Delete a model field. Deleting a field will also remove any data present in these fields on existing items.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field Type Description
model_id Number

The ID of the model

field_id Number

The ID of the field

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the model field could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Model field cannot be deleted as IP addresses are associated with this field on existing items.",
         "status_code": 422
     }
 }

Inventory_Items - Delete model

Delete a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field Type Description
id Number

The ID of the model

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the model could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Model cannot be deleted as inventory items are utilizing it.",
         "status_code": 422
     }
 }

Inventory_Items - Get all categories

Get a list of categories.

https://example.sonar.software/api/v1/inventory/categories

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the category

name String

The name of the category

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "CPE Radios"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

inventory_model_deployment_type_id optional Number

The ID of a valid inventory model deployment type for this item.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "users",
      "status": "functional",
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "Some data"
        },
        {
          "field_id": 2,
          "data": "00:AA:BB:CC:11:DD"
        }
      ],
      "inventory_model_deployment_type_id": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

snmp_override Array

An array containing a list of overridden fields to use for SNMP queries. See the 'Update SNMP Override' endpoint for details

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "accounts",
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "AA:BB:CC:DD:EE:FF"
        }
      ],
      "snmp_override": []
    },
    {
      "id": 2,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "accounts",
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "12:12:12:12:12:AB"
        }
      ],
      "snmp_override": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory items

Get all inventory items

https://example.sonar.software/api/v1/inventory/items/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "inventory_model_id": 2,
      "assignee_id": 1,
      "assignee_type": "users",
      "status": "functional",
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "Some data"
        },
        {
          "field_id": 2,
          "data": "00:AA:BB:CC:11:DD"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all inventory model deployment types

Get all inventory model deployment types

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types

Parameter

Field Type Description
inventory_model_id Integer

The ID of the inventory model to get the types for

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the inventory model deployment type.

deployment_type String

The name of the deployment type

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "deployment_type": "Backhaul"
    },
    {
      "id": 1,
      "deployment_type": "Access Point"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Inventory_Items - Get all manufacturers

Get a list of manufacturers.

https://example.sonar.software/api/v1/inventory/manufacturers

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

HTTP/1.1 200 OK
{
    "data": [
       {
            "id": 35,
            "name": "Cambium"
       },
       {
           "id": 36,
           "name": "Cisco"
       }
    ],
    "paginator": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all model fields

Get a list of model fields. This is not the data in the fields themselves - this is the definition of the fields on the model. When adding an inventory item, these fields will be present for each item.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the model

Success 200

Field Type Description
name String

The name of the field

id Number

The ID of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, it will be null.

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 9,
           "name": "MAC Address",
           "type": "mac",
           "is_required": true,
           "unique": true,
           "regexp": null
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all model fields

Get a list of model fields. This is not the data in the fields themselves - this is the definition of the fields on the model. When adding an inventory item, these fields will be present for each item.

https://example.sonar.software/api/v1/inventory/models/:id/fields

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the model

Success 200

Field Type Description
name String

The name of the field

id Number

The ID of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 9,
           "name": "MAC Address",
           "type": "mac",
           "is_required": true,
           "unique": true
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all models

Get a list of models. A model is the descriptor for an item - e.g. a Cisco 2940 switch would have a model of '2940' and a manufacturer of 'Cisco'

https://example.sonar.software/api/v1/inventory/models

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "name": "PMP450 5GHz AP",
           "manufacturer_id": 2,
           "inventory_model_category_id": 1,
           "https": false,
           "port": 80
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get all models

Get a list of models. A model is the descriptor for an item - e.g. a Cisco 2940 switch would have a model of '2940' and a manufacturer of 'Cisco'

https://example.sonar.software/api/v1/inventory/models

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "name": "PMP450 5GHz AP",
           "manufacturer_id": 2,
           "inventory_model_category_id": 1
       }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Items - Get an individual inventory model deployment type

Get an individual inventory model deployment type

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field Type Description
inventory_model_id Integer

The ID of the inventory model to get the type for

id Integer

The ID of the inventory model deployment type

Success 200

Field Type Description
id Integer

The ID of the inventory model deployment type.

deployment_type String

The name of the deployment type

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "CPE"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inventory_Items - Get individual category

Get an individual inventory model category.

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field Type Description
id Number

The ID of the category

Success 200

Field Type Description
id Number

The internal id of the category

name String

The name of the category

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the item

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

inventory_model_deployment_type_id optional Number

The ID of a valid inventory model deployment type for this item.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "users",
    "status": "functional",
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "Some data"
      },
      {
        "field_id": 2,
        "data": "00:AA:BB:CC:11:DD"
      }
    ],
    "inventory_model_deployment_type_id": null
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the item

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

snmp_override Array

An array containing a list of overridden fields to use for SNMP queries. See the 'Update SNMP Override' endpoint for details

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "accounts",
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "AA:BB:CC:DD:EE:FF"
      }
    ],
    "snmp_override": []
  }
}

Inventory_Items - Get individual inventory item

Get an individual item.

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the item

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "users",
    "status": "functional",
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "Some data"
      },
      {
        "field_id": 2,
        "data": "00:AA:BB:CC:11:DD"
      }
    ]
  }
}

Inventory_Items - Get individual manufacturer

Get an individual manufacturer.

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field Type Description
id Number

The ID of the manufacturer

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Cambium"
   }
}

Inventory_Items - Get individual model field

Get an individual model field.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field Type Description
model_id Number

The ID of the model

field_id Number

The ID of the field

Success 200

Field Type Description
id Number

The ID of the field

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If this is a regular expression field, this will be the PCRE regexp to run against the contents. If empty, this will be null.

HTTP/1.1 200 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Inventory_Items - Get individual model field

Get an individual model field.

https://example.sonar.software/api/v1/inventory/models/:model_id/fields/:field_id

Parameter

Field Type Description
model_id Number

The ID of the model

field_id Number

The ID of the field

Success 200

Field Type Description
id Number

The ID of the field

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If this is a regular expression field, this will be the PCRE regexp to run against the contents. If empty, this will be null.

HTTP/1.1 200 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Inventory_Items - Get individual model

Get an individual model.

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field Type Description
id Number

The ID of the model

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": false,
       "port": 12345
   }
}

Inventory_Items - Get individual model

Get an individual model.

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field Type Description
id Number

The ID of the model

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Inventory_Items - Mass delete items

Mass delete inventory items. Be very careful using this endpoint, you cannot restore deleted items!

https://example.sonar.software/api/v1/inventory/items

Parameter

Field Type Description
inventory_item_ids Array

An array of inventory item IDs to be deleted.

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the items could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": "Item cannot be deleted as the list of IDs is not valid.",
         "status_code": 422
     }
 }

Inventory_Items - Mass update inventory items

Mass update inventory items. This is frequently used in order to assign a large quantity of items to a new assignee, or to update the status of a group of items. You cannot update item fields using this endpoint - only the items themselves.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field Type Description
assignee_type optional String

The type of assignee to assign these items to. You can only move items to other entities that treat the items as undeployed. If you want to assign to an account, use the single update endpoint.

Allowed values: "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id optional Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

item_ids Array

An array that contains the IDs of all the items that should be updated.

status optional String

The status of the items.

Allowed values: "functional", "failed", "lost"

condition optional String

The condition of the items.

Allowed values: "new", "used"

consumed optional Boolean

Whether or not the item has been consumed.

purchase_price optional Number

The purchase price of the items.

{
    "assignee_type": "users",
    "assignee_id": 1,
    "status": "failed",
    "item_ids": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        10,
        53,
        4938
    ]
}

Success 200

Field Type Description
success Boolean

Will be true if the assignment was successful

HTTP/1.1 201 OK
{
  "data": {
       "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The item IDs 1,2,3,4 are not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Mass update inventory items

Mass update inventory items. This is frequently used in order to assign a large quantity of items to a new assignee, or to update the status of a group of items. You cannot update item fields using this endpoint - only the items themselves.

https://example.sonar.software/api/v1/inventory/items

Parameter

Field Type Description
assignee_type optional String

The type of assignee to assign these items to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id optional Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

item_ids Array

An array that contains the IDs of all the items that should be updated.

status optional String

The status of the items.

Allowed values: "functional", "failed", "lost"

condition optional String

The condition of the items.

Allowed values: "new", "used"

consumed optional Boolean

Whether or not the item has been consumed.

purchase_price optional Number

The purchase price of the items.

{
    "assignee_type": "users",
    "assignee_id": 1,
    "status": "failed",
    "item_ids": [
        1,
        2,
        3,
        4,
        5,
        6,
        7,
        10,
        53,
        4938
    ]
}

Success 200

Field Type Description
success Boolean

Will be true if the assignment was successful

HTTP/1.1 201 OK
{
  "data": {
       "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The item IDs 1,2,3,4 are not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update SNMP override

Override the SNMP authentication information for an item. This will override any defaults set on a monitoring template.

https://example.sonar.software/api/v1/inventory/items/:id/snmp_override

Parameter

Field Type Description
id Number

The ID of the item

enabled Boolean

Whether or not to enable the override

Default value: false

snmp_version optional Number

The SNMP version to use

Allowed values: 1, 2, 3

snmp_community optional String

The SNMP community/security name to use

snmp3_sec_level optional String

If you are using SNMPv3, this is the security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol optional String

If you are using SNMPv3, this is the authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase optional String

If you are using SNMPv3, this is the authentication pass phrase

snmp3_priv_protocol optional String

If you are using SNMPv3, this is the privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase optional String

If you are using SNMPv3, This is the privacy passphrase

snmp3_context_name optional String

If you are using SNMPv3, this is the context name

snmp3_context_engine_id optional String

If you are using SNMPv3, this is the default context EngineID

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

snmp_override Array

An array containing a list of overridden fields to use for SNMP queries.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "inventory_model_id": 2,
    "assignee_id": 1,
    "assignee_type": "accounts",
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "AA:BB:CC:DD:EE:FF"
      }
    ],
    "snmp_override": {
      "enabled": true,
      "snmp_version": 2,
      "snmp_community": "public",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null
    }
  }
}

Inventory_Items - Update category

Update an individual inventory model category

https://example.sonar.software/api/v1/inventory/categories/:id

Parameter

Field Type Description
id Number

The ID of the inventory model category

name String

The name for the inventory model category

Success 200

Field Type Description
id Number

The ID of the category

name String

The name of the category

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "CPE Radios"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name must be unique.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory item

Update an individual inventory item

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the inventory item

assignee_type optional String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id optional Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status optional String

The status of the device

Allowed values: "functional", "failed", "lost"

condition optional String

The condition of the device

Allowed values: "new", "used"

purchase_price optional Number

The purchase price of the item, in local currency. This is used for reporting.

consumed optional Boolean

If this is a consumable item (e.g. a spool of Ethernet cable) and the spool is consumed, set this to true.

fields optional Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

inventory_model_deployment_type_id optional Number

The ID of a valid inventory model deployment type for this item.

{
    "assignee_type": "vehicles",
    "assignee_id": 3,
    "status": "functional",
    "purchase_price": 10.53,
    "condition": "new",
    "fields": [
        {
            "field_id": 6,
            "data": "00:AA:BB:CC:DD:EF"
        },
        {
            "field_id": 7,
            "data": "Some data I want to store"
        }
    ],
    "inventory_model_deployment_type_id": 2
}

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
       "id": 68
       "inventory_model_id": 1,
       "assignee_type": "vehicles",
       "assignee_id": 3,
       "status": "functional",
       "consumed": false,
       "consumed_at": null
       "fields": [
           {
               "field_id": 6,
               "data": "00:AA:BB:CC:DD:EF"
           },
           {
               "field_id": 7,
               "data": "Some data I want to store"
           }
       ],
       "inventory_model_deployment_type_id": 2
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory item

Update an individual inventory item

https://example.sonar.software/api/v1/inventory/items/:id

Parameter

Field Type Description
id Number

The ID of the inventory item

assignee_type optional String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id optional Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status optional String

The status of the device

Allowed values: "functional", "failed", "lost"

condition optional String

The condition of the device

Allowed values: "new", "used"

purchase_price optional Number

The purchase price of the item, in local currency. This is used for reporting.

consumed optional Boolean

If this is a consumable item (e.g. a spool of Ethernet cable) and the spool is consumed, set this to true.

fields optional Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

{
    "assignee_type": "vehicles",
    "assignee_id": 3,
    "status": "functional",
    "purchase_price": 10.53,
    "condition": "new",
    "fields": [
        {
            "field_id": 6,
            "data": "00:AA:BB:CC:DD:EF"
        },
        {
            "field_id": 7,
            "data": "Some data I want to store"
        }
    ]
}

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

assignee_type String

The type of assignee to assign this item to

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles", "generic_inventory_assignees", "users"

assignee_id Number

The ID of the assignee (e.g. the ID of the vehicle, account, etc)

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
       "id": 68
       "inventory_model_id": 1,
       "assignee_type": "vehicles",
       "assignee_id": 3,
       "status": "functional",
       "consumed": false,
       "consumed_at": null
       "fields": [
           {
               "field_id": 6,
               "data": "00:AA:BB:CC:DD:EF"
           },
           {
               "field_id": 7,
               "data": "Some data I want to store"
           }
       ]
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "data": "The MAC Address field must be formatted as a MAC address in xx:xx:xx:xx:xx:xx format.",
         },
         "status_code": 422
     }
 }

Inventory_Items - Update inventory model deployment type

Update an existing inventory model deployment type.

https://example.sonar.software/api/v1/inventory/models/:inventory_model_id/inventory_model_deployment_types/:id

Parameter

Field Type Description
inventory_model_id Integer

The ID of the inventory model to update the type for

id Integer

The inventory model deployment type ID

deployment_type String

The name of the deployment type

Success 200

Field Type Description
id Integer

The ID of the inventory model deployment type.

deployment_type String
HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "deployment_type": "Backhaul"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Inventory_Items - Update manufacturer

Update a manufacturer

https://example.sonar.software/api/v1/inventory/manufacturers/:id

Parameter

Field Type Description
id Number

The ID of the manufacturer

name String

The name of the manufacturer

Success 200

Field Type Description
id Number

The internal id of the manufacturer

name String

The name of the manufacturer

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "Cambium"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Items - Update model field

Update a model field. When modifying existing fields, all existing data must adhere to the new type. For example, if you change a field from "string" to "mac", all existing data must match the requirements of the "mac" format.

https://example.sonar.software/api/v1/inventory/models/:id/fields/:field_id

Parameter

Field Type Description
id Number

The ID of the model

field_id Number

The ID of the field

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp optional String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field Type Description
name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, an OP/OPc value, an LTE auth key, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp", "op_opc", "lte_auth_key"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, this will be null.

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot enable the unique attribute on field MAC Address because there is duplicated data on existing items.",
     "status_code": 422
   }
 }

Inventory_Items - Update model field

Update a model field. When modifying existing fields, all existing data must adhere to the new type. For example, if you change a field from "string" to "mac", all existing data must match the requirements of the "mac" format.

https://example.sonar.software/api/v1/inventory/models/:id/fields/:field_id

Parameter

Field Type Description
id Number

The ID of the model

field_id Number

The ID of the field

name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp optional String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. For example, you could validate a MAC address with "/^([a-fA-F0-9]{2}:){5}[a-fA-F0-9]{2}$/". You can use https://regex101.com/ as a third party site to test/validate your regular expressions.

Success 200

Field Type Description
name String

The name of the field

type String

The type of field this is. Can be a string (any data), an integer (a number such as 1,2,3) a decimal (a number such as 1.0 or 4.55), a MAC address in XX:YY:ZZ:11:22:33 format, an IMSI number, or a regular expression. Regular expressions are entered in PCRE format.

Allowed values: "string", "integer", "decimal", "mac", "imsi", "regexp"

is_required Boolean

Whether or not the field is required to be completed when entering a new inventory item

unique Boolean

Whether or not the contents of this field must be unique. This is only within the context of the model itself - e.g. if you create a field named 'Serial Number' for a model with ID 1 and mark it as unique, all items added that correspond to model ID 1 must have unique data in the 'Serial Number' field, but another field named 'Serial Number' on model ID 2 would not conflict.

regexp String

If type is set to regexp, this is the regular expression to run against data input into this field, in PCRE format. If it is empty, this will be null.

HTTP/1.1 201 OK
{
    "data": {
       "id": 9,
       "name": "MAC Address",
       "type": "mac",
       "is_required": true,
       "unique": true,
       "regexp": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot enable the unique attribute on field MAC Address because there is duplicated data on existing items.",
     "status_code": 422
   }
 }

Inventory_Items - Update model

Update a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field Type Description
id Number

The ID of the model

manufacturer_id Number

The internal id of the manufacturer

name String

The name of the model

inventory_model_category_id Number

The category that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

https Boolean

Whether or not links to IPs associated with this inventory model should use HTTPS or HTTP

port Integer

The TCP port to use for clickable links to IPs associated with this model

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1,
       "https": false,
       "port": 432
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory_Items - Update model

Update a model

https://example.sonar.software/api/v1/inventory/models/:id

Parameter

Field Type Description
id Number

The ID of the model

manufacturer_id optional Number

The internal id of the manufacturer

name optional String

The name of the model

inventory_model_category_id optional Number

The category that this model is part of

Success 200

Field Type Description
id Number

The internal id of the model

name String

The name of the model

manufacturer_id Number

The ID of the manufacturer of the model

inventory_model_category_id Number

The ID of the category that this model is part of

HTTP/1.1 200 OK
{
    "data": {
       "id": 1,
       "name": "PMP450 5GHz AP",
       "manufacturer_id": 2,
       "inventory_model_category_id": 1
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

Inventory Location Addresses

Inventory_Location_Addresses - Create inventory location address

Create a new inventory location address

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses

Parameter

Field Type Description
inventory_location_id Number

The ID of the inventory location to add the address to

line1 String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision. You can obtain a valid list from _data/subdivisions/:country

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

The county, for US addresses

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Inventory_Location_Addresses - Delete inventory location address

Delete an inventory location address

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field Type Description
inventory_location_id Number

The ID of the inventory location

address_id Number

The ID of the address

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Address deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the address could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Inventory_Location_Addresses - Get all inventory location addresses

Get a list of the addresses for inventory location ID :inventory_location_id

https://example.sonar.software/api/v1/inventory_location/:inventory_location_id/addresses

Parameter

Field Type Description
inventory_location_id Number

The ID of the inventory location

limit optional Number

The number of entries to return

page optional Number

The page of results to return

county String

A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Inventory_Location_Addresses - Get individual inventory location address

Get an individual inventory location address.

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field Type Description
inventory_location_id Number

The ID of the inventory location

address_id Number

The ID of the address

county String

A valid county for the subdivision obtained from /_data/counties, null if not a US address

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Inventory_Location_Addresses - Update inventory location address

Update an inventory location address.

https://example.sonar.software/api/v1/inventory_locations/:inventory_location_id/addresses/:address_id

Parameter

Field Type Description
inventory_location_id Number

The ID of the inventory location to update the address on

address_id Number

The ID of the address

line1 optional String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city optional String

The city

state optional String

The state, province or other country subdivision

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be blank for any other country.

zip optional String

The ZIP/postal code

country optional String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude optional Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude optional Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id optional Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and will be null for any other country.

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Invoice Messages

Invoice_Messages - Create a new invoice message

Create a new invoice message.

https://example.sonar.software/api/v1/financial/invoices/invoice_messages

Parameter

Field Type Description
name String

A name for the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

Success 200

Field Type Description
id Integer

The ID of the invoice message.

name String

The name of the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

HTTP/1.1 201 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.biz",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_type_ids": "You must input at least one account type ID."
     },
     "status_code": 422
   }
 }

Invoice_Messages - Delete a invoice message

Delete a invoice message

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field Type Description
id Integer

The ID of the invoice message

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the invoice message could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "invoice message does not exist.",
         "status_code": 404
     }
 }

Invoice_Messages - Get all invoice messages

Get all invoice messages

https://example.sonar.software/api/v1/financial/invoices/invoice_messages

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the invoice message.

name String

The name of the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 6,
      "name": "Test message",
      "message": "This is a test message, I hope nobody sees it!",
      "account_type_ids": [
        1
      ]
    },
    {
      "id": 7,
      "name": "Commercial Message",
      "message": "Please remit payment through our business portal at www.example.biz",
      "account_type_ids": [
        2
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Invoice_Messages - Get an individual invoice message

Get an individual invoice message

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field Type Description
id Integer

The ID of the invoice message

Success 200

Field Type Description
id Integer

The ID of the invoice message.

name String

The name of the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.biz",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Invoice_Messages - Update invoice message

Update an existing invoice message.

https://example.sonar.software/api/v1/financial/invoices/invoice_messages/:id

Parameter

Field Type Description
id Integer

The invoice message ID

name String

A name for the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

Success 200

Field Type Description
id Integer

The ID of the invoice message.

name String

The name of the invoice message

message String

The invoice message

account_type_ids Array

An array of account type IDs that this invoice message should be appended for

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "name": "Commercial Message",
    "message": "Please remit payment through our business portal at www.example.software",
    "account_type_ids": [
      2
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job Types

Job_Types - Create a new job type

Create a new job type.

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

Default value: false

account_status_id_completion optional Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

Default value: false

account_status_id_failure optional Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are completed

Default value: false

completion_ticket_group_id optional Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are failed

Default value: false

failure_ticket_group_id optional Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks optional Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

Default value: true

task_template_id optional Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services optional Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success 200

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "Donut Run",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_status_id_completion": "The account status id completion field is required when change status on completion is 1."
     },
     "status_code": 422
   }
 }

Job_Types - Create a new job type

Create a new job type.

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

Default value: false

account_status_id_completion optional Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

Default value: false

account_status_id_failure optional Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are completed

Default value: false

completion_ticket_group_id optional Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are failed

Default value: false

failure_ticket_group_id optional Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks optional Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

Default value: true

task_template_id optional Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services optional Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success 200

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "name": "Donut Run",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "account_status_id_completion": "The account status id completion field is required when change status on completion is 1."
     },
     "status_code": 422
   }
 }

Job_Types - Delete a job type

Delete a job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field Type Description
id Integer

The ID of the job type

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the job type could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "job type does not exist.",
         "status_code": 404
     }
 }

Job_Types - Get all job types

Get all job types

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the job type.

name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Installation",
      "length_in_minutes": 90,
      "color": "blue",
      "icon": "smile",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [],
      "contract_template_id": 1
    },
    {
      "id": 2,
      "name": "Service Call",
      "length_in_minutes": 120,
      "color": "orange",
      "icon": "book",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [],
      "contract_template_id": null
    },
    {
      "id": 3,
      "name": "Job with services",
      "length_in_minutes": 15,
      "color": "purple",
      "icon": "folder",
      "change_status_on_completion": true,
      "account_status_id_completion": 4,
      "change_status_on_failure": true,
      "account_status_id_failure": 3,
      "create_completion_ticket": true,
      "completion_ticket_group_id": 1,
      "create_failure_ticket": true,
      "failure_ticket_group_id": 1,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [
        9,
        8
      ],
      "contract_template_id": null
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Job_Types - Get all job types

Get all job types

https://example.sonar.software/api/v1/scheduling/job_types

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the job type.

name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Installation",
      "length_in_minutes": 90,
      "color": "blue",
      "icon": "smile",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": []
    },
    {
      "id": 2,
      "name": "Service Call",
      "length_in_minutes": 120,
      "color": "orange",
      "icon": "book",
      "change_status_on_completion": false,
      "account_status_id_completion": null,
      "change_status_on_failure": false,
      "account_status_id_failure": null,
      "create_completion_ticket": false,
      "completion_ticket_group_id": null,
      "create_failure_ticket": false,
      "failure_ticket_group_id": null,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": []
    },
    {
      "id": 3,
      "name": "Job with services",
      "length_in_minutes": 15,
      "color": "purple",
      "icon": "folder",
      "change_status_on_completion": true,
      "account_status_id_completion": 4,
      "change_status_on_failure": true,
      "account_status_id_failure": 3,
      "create_completion_ticket": true,
      "completion_ticket_group_id": 1,
      "create_failure_ticket": true,
      "failure_ticket_group_id": 1,
      "allow_completion_with_uncompleted_tasks": false,
      "task_template_id": null,
      "services": [
        9,
        8
      ]
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Job_Types - Get an individual job type

Get an individual job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field Type Description
id Integer

The ID of the job type

Success 200

Field Type Description
id Integer

The ID of the job type.

name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Installation",
    "length_in_minutes": 90,
    "color": "blue",
    "icon": "smile",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": false,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Get an individual job type

Get an individual job type

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field Type Description
id Integer

The ID of the job type

Success 200

Field Type Description
id Integer

The ID of the job type.

name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Installation",
    "length_in_minutes": 90,
    "color": "blue",
    "icon": "smile",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": false,
    "task_template_id": null,
    "services": []
  }
}}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Update job type

Update an existing job type.

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field Type Description
id Integer

The ID of the job type

name optional String

The name of the job type

length_in_minutes optional Integer

The default length of time assigned for jobs of this type to be completed

color optional String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon optional String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

Default value: false

account_status_id_completion optional Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

Default value: false

account_status_id_failure optional Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are completed

Default value: false

completion_ticket_group_id optional Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are failed

Default value: false

failure_ticket_group_id optional Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks optional Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

Default value: true

task_template_id optional Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services optional Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

Success 200

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

contract_template_id optional Integer

Setting a contract template ID on a job type will automatically add this contract to an account when a job of this type is scheduled.

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "name": "Donut Walk",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": [],
    "contract_template_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Job_Types - Update job type

Update an existing job type.

https://example.sonar.software/api/v1/scheduling/job_types/:id

Parameter

Field Type Description
id Integer

The ID of the job type

name optional String

The name of the job type

length_in_minutes optional Integer

The default length of time assigned for jobs of this type to be completed

color optional String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon optional String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

Default value: false

account_status_id_completion optional Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure optional Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

Default value: false

account_status_id_failure optional Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are completed

Default value: false

completion_ticket_group_id optional Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket optional Boolean

If this is true, a ticket will be created when jobs of this type are failed

Default value: false

failure_ticket_group_id optional Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks optional Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

Default value: true

task_template_id optional Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services optional Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

Success 200

Field Type Description
name String

The name of the job type

length_in_minutes Integer

The default length of time assigned for jobs of this type to be completed

color String

The color of the job type on the schedule

Allowed values: "blue", "green", "red", "purple", "yellow", "orange", "grey"

icon String

The icon shown on jobs of this type on the schedule

Allowed values: "smile", "frown", "graph", "jellyfish", "car", "folder", "cookie", "book", "dna", "box"

change_status_on_completion Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are completed

account_status_id_completion Integer

If change_status_on_completion is true, this is the account status ID that the account will be changed to when jobs of this type are completed

change_status_on_failure Boolean

Set this to true if you want the status on an account to be changed when jobs of this type are failed

account_status_id_failure Integer

If change_status_on_failure is true, this is the account status ID the account will be changed to when jobs of this type are failed

create_completion_ticket Boolean

If this is true, a ticket will be created when jobs of this type are completed

completion_ticket_group_id Integer

If create_completion_ticket is true, then tickets created on completion will be assigned to this ticket group ID

create_failure_ticket Boolean

If this is true, a ticket will be created when jobs of this type are failed

failure_ticket_group_id Integer

If create_failure_ticket is true, then tickets created on failure will be assigned to this ticket group ID

allow_completion_with_uncompleted_tasks Boolean

If this is false, jobs of this type cannot be completed while they have uncompleted tasks on them

task_template_id Integer

Setting a task template on a job type will automatically create all tasks defined in the template on jobs created of this type

services Array

An array of service IDs. If service IDs are set here, when jobs of this type are completed while assigned to an account, the account will have all services listed here added to it or charged to it. Only allows recurring, expiring, or one time services.

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "name": "Donut Walk",
    "length_in_minutes": 15,
    "color": "orange",
    "icon": "cookie",
    "change_status_on_completion": false,
    "account_status_id_completion": null,
    "change_status_on_failure": false,
    "account_status_id_failure": null,
    "create_completion_ticket": false,
    "completion_ticket_group_id": null,
    "create_failure_ticket": false,
    "failure_ticket_group_id": null,
    "allow_completion_with_uncompleted_tasks": true,
    "task_template_id": null,
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check in to a job

Check a user in to a job. This is used when the user is on site and starting the job. Multiple users can check in to a job at the same time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_in

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check in to the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [
         [
              "user_id": 1,
              "datetime": "2016-01-01 01:01:01"
         ]
    ],
    "services": [
        1
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Check out of a job

Check a user out of a job. This should only be used to remove a user from a checked in job prior to completion. Completing or failing a job will automatically remove all checked in users.

https://example.sonar.software/api/v1/scheduling/jobs/:id/check_out

Parameter

Field Type Description
id Integer

The job ID

user_id Integer

The ID of the user to check out of the job. If not submitted, the user ID of the logged in user will be used.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": "2016-01-01 01:02:03",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "scheduled",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

Completing a job will move the status to completed or failed, remove it from the schedule, remove all checked in users, add any services to the account that are associated with the job, and perform all events associated with the job type.

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description
id Integer

The job ID

completion_type String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": "2018-09-23 12:23:34,
    "completed_by_user_id": 1,
    "completed_successfully": true,
    "completion_reason": "foobar"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

Completing a job will move the status to completed or failed, remove it from the schedule, remove all checked in users, add any services to the account that are associated with the job, and perform all events associated with the job type.

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description
id Integer

The job ID

completion_type String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Complete a job

Completing a job will move the status to completed or failed, remove it from the schedule, remove all checked in users, add any services to the account that are associated with the job, and perform all events associated with the job type.

https://example.sonar.software/api/v1/scheduling/jobs/:id/complete

Parameter

Field Type Description
id Integer

The job ID

completion_type String

,"failure" Whether or not the job was successfully completed

Default value: success

reason optional String

The reason for the job failure, or some notes on success. Required when failing a job.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "completed",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Create a new desired job date/time

Create a new desired job date/time. This lets you specify when a customer would like to have the job performed as a date, a start time, and an end time, which denotes the range of time they will be available.

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes

Parameter

Field Type Description
id Number

The ID of the job

date Date

The date, in Y-m-d format

start_time Time

The start time of the time range, in H:m:s format (24 hour)

end_time Time

The end time of the time range, in H:m:s format (24 hour)

Success 200

Field Type Description
id Number

The ID of the desired job date/time.

date Date

The date, in Y-m-d format

start_time Time

The start time of the time range, in H:m:s format (24 hour)

end_time Time

The end time of the time range, in H:m:s format (24 hour)

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "09:00:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "The start_time must be prior to the end_time.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
job_type_id Number

The ID of a job type

assigned_type String

The entity you are assigning this job to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule or reschedule this job, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. scheduled_datetime is required if this is submitted.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

ticket_id optional Integer

ID of a ticket that this job is linked to. If null is sent, the job will not be linked to a ticket.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
job_type_id Number

The ID of a job type

assigned_type String

The entity you are assigning this job to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule or reschedule this job, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. scheduled_datetime is required if this is submitted.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

ticket_id optional Integer

ID of a ticket that this job is linked to. If null is sent, the job will not be linked to a ticket.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Create a new job

Create a new job.

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
job_type_id Number

The ID of a job type

assigned_type String

The entity you are assigning this job to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule or reschedule this job, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. scheduled_datetime is required if this is submitted.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "There is no availability for that day/time for user ID 1.",
     "status_code": 422
   }
 }

Jobs - Delete a desired job date/time

Delete a desired job date/time

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field Type Description
id Number

The ID of the job

desired_job_datetime_id Number

The ID of the desired job date/time

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the desired job date/time could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "desired job date/time does not exist.",
         "status_code": 404
     }
 }

Jobs - Delete a job

Delete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
id Number

The ID of the job

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the job could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "job does not exist.",
         "status_code": 404
     }
 }

Jobs - Delete a job

Delete a job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
id Number

The ID of the job

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the job could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "job does not exist.",
         "status_code": 404
     }
 }

Jobs - Find any available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users.

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users optional Array

An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.

entityType String

One of account or network_site. This is to limit results to entries that meet any defined geofences.

entityId Integer

The ID of an account or network_site. This is to limit results to entries that meet any defined geofences.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find any available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users.

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users optional Array

An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find any available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users.

https://example.sonar.software/api/v1/scheduling/jobs/find_any_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users optional Array

An array of user IDs that you want to schedule this job for. If this is omitted, all users will be checked.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date. Below that are multiple objects, where the property is the user ID, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-09-16": {
      "1": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "15:47:00"
        },
        {
          "start": "16:02:00",
          "end": "17:20:00"
        },
        {
          "start": "18:20:00",
          "end": "21:00:00"
        }
      ],
      "2": [
        {
          "start": "04:00:00",
          "end": "10:00:00"
        },
        {
          "start": "15:00:00",
          "end": "16:56:00"
        },
        {
          "start": "17:26:00",
          "end": "21:00:00"
        }
      ]
    }
  }
}

Jobs - Find compound available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users. This data is compounded by all the users entered (e.g. if you submit 3 user IDs, it will only return time where all three of those users are available to perform a job of the type submitted.)

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users Array

An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.

entityType String

One of account or network_site. This is to limit results to entries that meet any defined geofences.

entityId Integer

The ID of an account or network_site. This is to limit results to entries that meet any defined geofences.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Find compound available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users. This data is compounded by all the users entered (e.g. if you submit 3 user IDs, it will only return time where all three of those users are available to perform a job of the type submitted.)

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users Array

An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Find compound available space for a job

Return available blocks of time for a job. You can use this to quickly find available time blocks for a job of a specific length in a date range that you want to schedule for a specific user or group of users. This data is compounded by all the users entered (e.g. if you submit 3 user IDs, it will only return time where all three of those users are available to perform a job of the type submitted.)

https://example.sonar.software/api/v1/scheduling/jobs/find_available_space

Parameter

Field Type Description
start_date DateTime

The start date for the date range in YYYY-MM-DD format.

end_date DateTime

The end date for the date range in YYYY-MM-DD format.

length_in_minutes Integer

The length of time required for the job, in minutes

job_type_id Integer

A valid job type ID

users Array

An array of user IDs that you want to schedule this job for. You can include a single ID if you want to schedule for a single user.

Success 200

Field Type Description
data Object

An object of results, where the primary property is the date, and the value is an array of objects with start and end, showing the available time blocks that match the criteria.

HTTP/1.1 200 OK
{
  "data": {
    "2016-09-16": [
      {
        "start": "04:00:00",
        "end": "10:00:00"
      },
      {
        "start": "15:19:00",
        "end": "16:56:00"
      },
      {
        "start": "18:20:00",
        "end": "21:00:00"
      }
    ],
    "2016-09-18": [
      {
        "start": "00:00:00",
        "end": "01:00:00"
      }
    ],
    "2016-09-19": [
      {
        "start": "00:00:00",
        "end": "21:00:00"
      }
    ]
  }
}

Jobs - Get all desired job date/times

Get all desired job date/times for a job

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the job

Success 200

Field Type Description
id Number

The ID of the desired job date/time.

date Date

The date, in Y-m-d format

start_time Time

The start time of the time range, in H:m:s format (24 hour)

end_time Time

The end time of the time range, in H:m:s format (24 hour)

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "date": "2016-09-01",
      "start_time": "07:00:00",
      "end_time": "09:00:00"
    },
    {
      "id": 2,
      "date": "2016-10-01",
      "start_time": "09:00:00",
      "end_time": "11:30:00"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": [] ,
        "completed_at": null,
        "completed_by_user_id": null,
        "completed_successfully": null,
        "completion_reason": null
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": []
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get all jobs

Get all jobs

https://example.sonar.software/api/v1/scheduling/jobs

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 200 OK
{
  "data": [
    {
       "id": 8,
       "scheduled_datetime": null,
       "job_type_id": 1,
       "length_in_minutes": 60,
       "ticket_id": null,
       "assigned_type": "accounts",
       "assigned_id": 1,
       "notes": "Please replace the router.",
       "status": "queued",
       "user_ids": [],
       "created_by_user_id": 1,
       "checked_in_users": [],
       "services": []
     }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Jobs - Get an individual desired job date/time

Get an individual desired job date/time

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field Type Description
id Number

The ID of the job

desired_job_datetime_id Number

The ID of the desired job date/time

Success 200

Field Type Description
id Number

The ID of the desired job date/time.

date Date

The date, in Y-m-d format

start_time Time

The start time of the time range, in H:m:s format (24 hour)

end_time Time

The end time of the time range, in H:m:s format (24 hour)

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "09:00:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
id Number

The ID of the job

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
id Number

The ID of the job

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": []
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Get an individual job

Get an individual job

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
id Number

The ID of the job

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user who created this job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 200 OK
{
  "data": {
     "id": 8,
     "scheduled_datetime": null,
     "job_type_id": 1,
     "length_in_minutes": 60,
     "ticket_id": null,
     "assigned_type": "accounts",
     "assigned_id": 1,
     "notes": "Please replace the router.",
     "status": "queued",
     "user_ids": [],
     "created_by_user_id": 1,
     "checked_in_users": [],
     "services": []
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field Type Description
id Number

The job ID

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field Type Description
id Number

The job ID

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Return a job to the queue

Move a job back into the queue. This will take a scheduled or failed job, and put it back into the queue.

https://example.sonar.software/api/v1/scheduling/jobs/:id/queue

Parameter

Field Type Description
id Number

The job ID

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "scheduled_datetime": null,
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Please replace the router.",
    "status": "queued",
    "user_ids": [],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update desired job date/time

Update an existing desired job date/time.

https://example.sonar.software/api/v1/scheduling/jobs/:id/desired_job_datetimes/:desired_job_datetime_id

Parameter

Field Type Description
id Number

The job ID

desired_job_datetime_id NUmber

The ID of the desired job date/time

date optional Date

The date, in Y-m-d format

start_time optional Time

The start time of the time range, in H:m:s format (24 hour)

end_time optional Time

The end time of the time range, in H:m:s format (24 hour)

Success 200

Field Type Description
id Number

The ID of the desired job date/time.

date Date

The date, in Y-m-d format

start_time Time

The start time of the time range, in H:m:s format (24 hour)

end_time Time

The end time of the time range, in H:m:s format (24 hour)

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "date": "2016-09-01",
    "start_time": "07:00:00",
    "end_time": "11:45:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
assigned_type optional String

The entity you are assigning this job to. This is required if you input assigned_id.

Allowed values: "accounts", "network_sites"

assigned_id optional Number

The ID of the entity. This is required if you input assigned_type.

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule this job now, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a scheduled_datetime.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

ticket_id Integer

ID of a ticket that this job is linked to. If null is sent, the job will not be linked to a ticket.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

completed_at DateTime

The date and time the job was completed, if it is complete.

completed_by_user_id Integer

The ID of the user that completed the job, if it is complete.

completed_successfully Boolean

If the job is complete, this will be true or false to show if the job was completed successfully.

completion_reason String

The reason given upon job completion, if the job is complete.

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": [] ,
    "completed_at": null,
    "completed_by_user_id": null,
    "completed_successfully": null,
    "completion_reason": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
assigned_type optional String

The entity you are assigning this job to. This is required if you input assigned_id.

Allowed values: "accounts", "network_sites"

assigned_id optional Number

The ID of the entity. This is required if you input assigned_type.

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule this job now, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a scheduled_datetime.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

ticket_id Integer

ID of a ticket that this job is linked to. If null is sent, the job will not be linked to a ticket.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Jobs - Update job

Update an existing job. You can use this to reschedule an already scheduled job, or to schedule a queued job as well.

https://example.sonar.software/api/v1/scheduling/jobs/:id

Parameter

Field Type Description
job_type_id optional Number

The ID of a job type

assigned_type optional String

The entity you are assigning this job to. This is required if you input assigned_id.

Allowed values: "accounts", "network_sites"

assigned_id optional Number

The ID of the entity. This is required if you input assigned_type.

length_in_minutes optional Number

The length of the job. Will be inherited from the job type if omitted. Must be divisible by 15.

notes optional String

Any notes for the job.

scheduled_datetime optional DateTime

If you want to schedule this job now, input a date/time to schedule it for. user_ids is required if this is submitted. The timezone should be the timezone of this Sonar instance.

user_ids optional Array

Input an array of user_ids to assign this job to. These are the parties that will be completing the job. They must all have available time in their schedules for the job. This will be ignored if the job is not currently scheduled, or you do not submit a scheduled_datetime.

services optional Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

Success 200

Field Type Description
id Number

The ID of the job.

scheduled_datetime DateTime

When the job is scheduled for, in the timezone of this Sonar instance.

job_type_id Number

The ID of the job type

length_in_minutes Number

The time allotted for the job

ticket_id Number

The ID of a ticket this job is associated with

assigned_type String

The entity this job is assigned to

Allowed values: "accounts", "network_sites"

assigned_id Number

The ID of the entity this job is assigned to

notes String

Some notes for the job

status String

The current status of the job

Allowed values: "queued", "scheduled", "failed", "completed"

user_ids Array

An array of user IDs that are assigned to complete this job.

created_by_user_id Integer

The ID of the user that created the job

checked_in_users Array

An array of arrays, where the internal arrays have an integer of user_id for the user ID that is checked in, and an UTC date/time of datetime for the date and time they checked in.

services Array

An array of service IDs that will be added to the account when the job is completed. The job can also have services added by the job type - query the job types endpoint to see those.

HTTP/1.1 201 OK
{
  "data": {
    "id": 22,
    "scheduled_datetime": "2016-08-29 11:00",
    "job_type_id": 1,
    "length_in_minutes": 60,
    "ticket_id": null,
    "assigned_type": "accounts",
    "assigned_id": 1,
    "notes": "Replace the Cisco router with a Juniper router.",
    "status": "scheduled",
    "user_ids": [
      1
    ],
    "created_by_user_id": 1,
    "checked_in_users": [],
    "services": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Mapping

Mapping - Get GeoJSON data

Get GeoJSON for specific data inside Sonar. This can be used to display your geographical data on an external map. This data is cached, and only updates once every minute.

https://example.sonar.software/api/v1/mapping/geojson/:type

Parameter

Field Type Description
type String

The type of data to get.

Allowed values: "accounts", "network_sites", "inventory_locations", "vehicles"

Success 200

Field Type Description
data Object

Returns data in GeoJSON format - documented at http://geojson.org/. Each type returns different properties that are relevant to the type being returned. The vehicles endpoint returns a MultiPoint feature, which shows the last 100 points tracked for the vehicle. Vehicle data is only available if you have enabled GPS tracking inside Sonar. The most current location is the first element in the array.

 HTTP/1.1 200 OK
 {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -80.33397,
            39.96938
          ]
        },
        "properties": {
          "id": 1,
          "name": "Some Test Account",
          "account_type": "Residential",
          "account_status": "Active",
          "status_color": "#3498db"
        }
      },
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -106.53,
            34.591
          ]
        },
        "properties": {
          "id": 2,
          "name": "Prof. Luna O'Hara V",
          "account_type": "Commercial",
          "account_status": "Lead",
          "status_color": "#9b59b6"
        }
      }
    ]
}
 HTTP/1.1 200 OK
 {
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -85.34969,
            42.289
          ],
          [
            -85.34969,
            42.289
          ],
          [
            -85.34969,
            42.289
          ]
        ]
      },
      "properties": {
        "id": 1,
        "name": "My Test Vehicle",
        "manufacturer": "Ford",
        "model": "F150",
        "year": 2009,
        "license_plate": "12345",
        "vin": "ABC123",
        "other_data": {
          "Name": "Steve-(16)",
          "Status": "Key Off (IS)"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [
            -84.48617,
            42.2381
          ],
          [
            -84.31253,
            42.2381
          ]
        ]
      },
      "properties": {
        "id": 2,
        "name": "Another Vehicle",
        "manufacturer": "Chevrolet",
        "model": "Camaro",
        "year": 2008,
        "license_plate": "1234512345",
        "vin": "ABCDEFG",
        "other_data": {
          "Name": "Roger Steele (13)",
          "Status": "Key On (IS)"
        }
      }
    }
  ]
}

Mapping - Get GeoJSON data

Get GeoJSON for specific data inside Sonar. This can be used to display your geographical data on an external map. This data is cached, and only updates once every minute.

https://example.sonar.software/api/v1/mapping/geojson/:type

Parameter

Field Type Description
type String

The type of data to get.

Allowed values: "accounts", "network_sites", "inventory_locations"

Success 200

Field Type Description
data Object

Returns data in GeoJSON format - documented at http://geojson.org/. Each type returns different properties that are relevant to the type being returned.

 HTTP/1.1 200 OK
 {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -80.33397,
            39.96938
          ]
        },
        "properties": {
          "id": 1,
          "name": "Some Test Account",
          "account_type": "Residential",
          "account_status": "Active",
          "status_color": "#3498db"
        }
      },
      {
        "type": "feature",
        "geometry": {
          "type": "Point",
          "coordinates": [
            -106.53,
            34.591
          ]
        },
        "properties": {
          "id": 2,
          "name": "Prof. Luna O'Hara V",
          "account_type": "Commercial",
          "account_status": "Lead",
          "status_color": "#9b59b6"
        }
      }
    ]
}

Mapping - Get a mapping of network sites, inventory items, and subscriber IPs

Retrieve a mapping of network data, pulled using the Sonar poller. This endpoint is explicitly in place to enable integration with external systems. The data is keyed by network site ID and inventory item ID respectively, to make integration with external systems easier.

https://example.sonar.software/api/v1/network/mapping

Success 200

Field Type Description
id Integer

The ID of the network site

name String

The name of the network site

inventory_items Object

An object containing inner objects, keyed by the inventory item ID, representing the inventory items deployed at this network site. The lines below describe the content of each inventory item object.

category String

The model category of the inventory item

model_name String

The model name of the inventory item

ip_description String

The description of the IP address assigned to the device, if there is one.

merged_description String

A human friendly description that can be used for the device.

ip_address String

The IP address of the inventory item

subscribers Array

An array of subscriber data (name, id, and an array of IP addressess), for subscribers that are attached to this inventory item.

 HTTP/1.1 201 OK
 {
     "data": {
         "1": {
             "id": 1,
             "name": "A-002 DeBolt",
             "inventory_items": {
                 "2531": {
                     "id": 2531,
                     "category": "Access Points",
                     "model_name": "PMP 450 3.6 Ghz AP",
                     "ip_address": "172.20.1.10",
                     "ip_description": "A-002-36450AP-01",
                     "merged_description": "PMP 450 3.6 Ghz AP (172.20.1.10) - A-002-36450AP-01",
                     "subscriber_data": [],
                     "subscribers": {
                         "28": {
                             "name": "Tom & Alisa Burton",
                             "id": 28,
                             "ips": [
                                 "10.1.1.33/32",
                             ]
                         },
                         "35": {
                             "name": "Ellen Moore",
                             "id": 35,
                             "ips": [
                                 "10.1.1.89/32",
                             ]
                         },
                         "47": {
                             "name": "Jason Moody",
                             "id": 47,
                             "ips": [
                                 "10.1.1.57/32",
                                 "192.168.82.35/32"
                             ]
                         },
                         "49": {
                             "name": "828859 Alberta Ltd",
                             "id": 49,
                             "ips": [
                                 "10.1.1.50/32"
                             ]
                         }
                    }
            }
        }
    }
}

Monitoring Data

Monitoring_Data - Get monitoring data

Get monitoring data, between start_date and end_date for inventory item with ID inventory_item_id, as long as it was assigned to entity with entity_id. The results for this are in a fairly complex structure, and are meant to be used for inclusion in external data display systems.

https://example.sonar.software/api/v1/network/monitoring/monitoring_data/{entity}/{entity_id}/inventory_items/{inventory_item_id}/{start_date}/{end_date}

Parameter

Field Type Description
entity String

The entity

Allowed values: "accounts", "network_sites"

entity_id Integer

The ID of the entity

inventory_item_id Integer

The ID of the inventory item that was being monitored

start_date Date

The start date, in YYYY-MM-DD format

end_date Date

The end date, in YYYY-MM-DD format

Success 200

Field Type Description
template_details Object

An object containing details on the template that has been used to control the data to monitor. See the monitoring templates section for more details.

status Object

This object contains two arrays, snmp and icmp. Each array contains multiple arrays with three values. The first is a unix timestamp for when the data was retrieved. The second is an integer, 0 means down, 1 means warning, and 2 means good. The third is an optional string that will describe the reason the device is in down or warning.

snmp Object

This object contains the results for all the SNMP OIDs defined in template_details. Each property in this object is the ID of an SNMP OID. The value is an array of arrays, where each array contains two values. The first value is the unix timestamp when the data was collected. The second value is the value collected.

icmp Array

This array contains the results for any ICMP monitoring performed. There are multiple arrays contained within, each with 5 values. The first value is the unix timestamp when the data was collected. The next four values are the lowest latency value, the median latency value, the maximum latency value, and the packet loss percentage for that timestamp.

interfaces Object

This object contains the latest interface details for each interface being monitored. Each property in this object is the name of the interface being monitored. Each property has an associated object, which contains a list of standard Ethernet MIB names, and then an array of arrays, which will only contain a single array with the most current value in it. The first value in the array is a unix timestamp of when the data was collected, and the second value is the actual data collected.

HTTP/1.1 201 OK
{
  "data": {
    "template_details": {
      "name": "MikroTik",
      "icmp_latency_threshold": 500,
      "icmp_loss_threshold": 50,
      "icmp": true,
      "collect_interface_statistics": true,
      "graphs": {
        "15": {
          "type": "line",
          "stacked": false,
          "name": "Memory"
        }
      },
      "snmp_oids": {
        "17": {
          "id": 17,
          "name": "Total Memory",
          "color": "#1abc9c",
          "unit_of_measurement": "MB",
          "graph_id": 15,
          "oid": "1.3.6.1.2.1.25.2.3.1.5.65536",
          "thresholds": [

          ]
        },
        "16": {
          "id": 16,
          "name": "Used Memory",
          "color": "#e74c3c",
          "unit_of_measurement": "MB",
          "graph_id": 15,
          "oid": "1.3.6.1.2.1.25.2.3.1.6.65536",
          "thresholds": [

          ]
        },
        "15": {
          "id": 15,
          "name": "CPU Usage",
          "color": "#e74c3c",
          "unit_of_measurement": "%",
          "graph_id": null,
          "oid": "1.3.6.1.2.1.25.3.3.1.2.1",
          "thresholds": [
            {
              "operator": "gte",
              "value": "50",
              "time_period_in_minutes": 15
            }
          ]
        }
      }
    },
    "status": {
      "snmp": [
        [
          1481041629,
          2,
          ""
        ],
        [
          1481041716,
          2,
          ""
        ],
        [
          1481041803,
          2,
          ""
        ],
        [
          1481041890,
          2,
          ""
        ],
        [
          1481041977,
          2,
          ""
        ],
        [
          1481042064,
          2,
          ""
        ],
        [
          1481042151,
          2,
          ""
        ],
        [
          1481042238,
          2,
          ""
        ],
        [
          1481042325,
          2,
          ""
        ],
        [
          1481042412,
          2,
          ""
        ],
        [
          1481042499,
          2,
          ""
        ],
        [
          1481042586,
          2,
          ""
        ],
        [
          1481042673,
          2,
          ""
        ],
        [
          1481042760,
          2,
          ""
        ]
      ],
      "icmp": [
        [
          1481041629,
          2,
          ""
        ],
        [
          1481041716,
          2,
          ""
        ],
        [
          1481041803,
          2,
          ""
        ],
        [
          1481041890,
          2,
          ""
        ],
        [
          1481041977,
          2,
          ""
        ],
        [
          1481042064,
          2,
          ""
        ],
        [
          1481042151,
          2,
          ""
        ],
        [
          1481042238,
          2,
          ""
        ],
        [
          1481042325,
          2,
          ""
        ],
        [
          1481042412,
          2,
          ""
        ],
        [
          1481042499,
          2,
          ""
        ],
        [
          1481042586,
          2,
          ""
        ],
        [
          1481042673,
          2,
          ""
        ],
        [
          1481042760,
          2,
          ""
        ]
      ]
    },
    "snmp": {
      "17": [
        [
          1481041629,
          131072
        ],
        [
          1481041716,
          131072
        ],
        [
          1481041803,
          131072
        ],
        [
          1481041890,
          131072
        ],
        [
          1481041977,
          131072
        ],
        [
          1481042064,
          131072
        ],
        [
          1481042151,
          131072
        ],
        [
          1481042238,
          131072
        ],
        [
          1481042325,
          131072
        ],
        [
          1481042412,
          131072
        ],
        [
          1481042499,
          131072
        ],
        [
          1481042586,
          131072
        ],
        [
          1481042673,
          131072
        ],
        [
          1481042760,
          131072
        ]
      ],
      "16": [
        [
          1481041629,
          34172
        ],
        [
          1481041716,
          34056
        ],
        [
          1481041803,
          34088
        ],
        [
          1481041890,
          34024
        ],
        [
          1481041977,
          34024
        ],
        [
          1481042064,
          34024
        ],
        [
          1481042151,
          34024
        ],
        [
          1481042238,
          34008
        ],
        [
          1481042325,
          34024
        ],
        [
          1481042412,
          34072
        ],
        [
          1481042499,
          34072
        ],
        [
          1481042586,
          34064
        ],
        [
          1481042673,
          34024
        ],
        [
          1481042760,
          34032
        ]
      ],
      "15": [
        [
          1481041629,
          2
        ],
        [
          1481041716,
          2
        ],
        [
          1481041803,
          2.5
        ],
        [
          1481041890,
          2
        ],
        [
          1481041977,
          2.5
        ],
        [
          1481042064,
          0
        ],
        [
          1481042151,
          1
        ],
        [
          1481042238,
          3
        ],
        [
          1481042325,
          11
        ],
        [
          1481042412,
          2
        ],
        [
          1481042499,
          3
        ],
        [
          1481042586,
          3
        ],
        [
          1481042673,
          3
        ],
        [
          1481042760,
          6.5
        ]
      ]
    },
    "icmp": [
      [
        1481041629,
        0.42,
        0.46,
        0.5,
        0
      ],
      [
        1481041716,
        0.44,
        0.49,
        0.98,
        0
      ],
      [
        1481041803,
        0.41,
        0.465,
        0.99,
        0
      ],
      [
        1481041890,
        0.41,
        0.47,
        0.51,
        0
      ],
      [
        1481041977,
        0.39,
        0.495,
        0.56,
        0
      ],
      [
        1481042064,
        0.46,
        0.49,
        0.92,
        0
      ],
      [
        1481042151,
        0.42,
        0.48,
        0.64,
        0
      ],
      [
        1481042238,
        0.41,
        0.47,
        1.01,
        0
      ],
      [
        1481042325,
        0.45,
        0.49,
        0.55,
        0
      ],
      [
        1481042412,
        0.39,
        0.48,
        1.06,
        0
      ],
      [
        1481042499,
        0.44,
        0.47,
        0.65,
        0
      ],
      [
        1481042586,
        0.45,
        0.49,
        0.62,
        0
      ],
      [
        1481042673,
        0.44,
        0.47,
        0.5,
        0
      ],
      [
        1481042760,
        0.43,
        0.475,
        1.08,
        0
      ]
    ],
    "interfaces": {
      "bridge-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            56.545977011494
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            5174.1609195402
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            35.16091954023
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            63527.310344828
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            100000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            209
          ]
        ]
      },
      "ether1-gateway": {
        "IfOutUcastPkts": [
          [
            1481041716,
            27.850574712644
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            56059.454022989
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            134.99425287356
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            5230.4597701149
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            1000000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether10-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether2": {
        "IfOutUcastPkts": [
          [
            1481041716,
            22.022988505747
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            4140.9770114943
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            18.816091954023
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            18658.017241379
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            100000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether3": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether4": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether5": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether6-master-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether7-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether8-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "ether9-slave-local": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "sfp1": {
        "IfOutUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            0
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            0
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            2
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            0
          ]
        ],
        "ifType": [
          [
            1481041629,
            6
          ]
        ]
      },
      "wlan1": {
        "IfOutUcastPkts": [
          [
            1481041716,
            37.362068965517
          ]
        ],
        "ifInDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifInErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifInOctets": [
          [
            1481041716,
            1800.7011494253
          ]
        ],
        "ifInUcastPkts": [
          [
            1481041716,
            17.844827586207
          ]
        ],
        "ifInUnknownProtos": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutDiscards": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutErrors": [
          [
            1481041716,
            0
          ]
        ],
        "ifOutOctets": [
          [
            1481041716,
            45367.350574713
          ]
        ],
        "ifAdminStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifLastChange": [
          [
            1481041629,
            0
          ]
        ],
        "ifMtu": [
          [
            1481041629,
            1500
          ]
        ],
        "ifOperStatus": [
          [
            1481041629,
            1
          ]
        ],
        "ifSpeed": [
          [
            1481041629,
            11000000
          ]
        ],
        "ifType": [
          [
            1481041629,
            71
          ]
        ]
      }
    }
  }
}

Monitoring Templates

Monitoring_Templates - Create a new SNMP OID threshold

Create a new SNMP OID threshold. Defining thresholds allows you to move a device into a threshold violating status when it crosses a certain boundary. For example, you can define a threshold that CPU usage must remain below 50% by using the operator lt and the value 50 on an SNMP OID that pulls CPU usage.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

snmp_oid_id Integer

The ID of the SNMP OID

operator String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes Integer

The amount of time that the threshold must be violated before it is triggered

Success 200

Field Type Description
id Integer

The ID of the SNMP OID threshold.

operator String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes Integer

The amount of time that the threshold must be violated before it is triggered

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 422
 {
   "error": {
     "message": "That SNMP OID does not exist.",
     "status_code": 404
   }
 }

Monitoring_Templates - Create a new SNMP OID

Create a new SNMP OID.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template to add this OID to.

name String

A name for the SNMP OID

oid String

A numeric OID

color optional String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement optional String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id optional Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale optional Boolean

Whether or not to automatically scale this OID in thousands.

Default value: false

display_as_table optional Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Default value: false

Success 200

Field Type Description
id Number

The ID of the SNMP OID.

name String

The name of the SNMP OID

oid String

The numeric OID

color String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale Boolean

Whether or not results from this OID are automatically scaled by thousands.

display_as_table Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "oid": "1.2.3.4",
    "name": "Test",
    "color": "#3498db",
    "unit_of_measurement": null,
    "monitoring_graph_id": null,
    "auto_scale": false,
    "display_as_table": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "oid": "The oid has already been taken."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Create a new monitoring graph

Create a new monitoring graph. This is a graph definition that can be associated with multiple SNMP OIDs, in order to graph multiple results on a single graph.

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template this graph will be available for

name String

A name for the monitoring graph

type String

The type of graph

Allowed values: "line", "bar", "area"

stacked Boolean

Whether or not values should be stacked on the graph, or drawn independently

Default value: false

Success 200

Field Type Description
id Integer

The ID of the monitoring graph.

name String

The name of the monitoring graph

type String

The type of graph

stacked Boolean

Whether or not values should be stacked on the graph, or drawn independently

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "type": "The selected type is invalid."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Create a new monitoring template

Create a new monitoring template. A monitoring template is a template that defines items to monitor on an inventory model.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates
{
     "name": "Standard CPE Template",
     "snmp_version": 2,
     "snmp_community": "public",
     "icmp": false,
     "collect_interface_statistics": true,
     "inventory_model_ids": [
          1,
          2,
          5
     ]
}

Parameter

Field Type Description
name String

A name for the monitoring template

snmp_version optional Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community optional String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level optional String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol optional String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase optional String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol optional String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase optional String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name optional String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id optional String

If you are using SNMPv3, this is the default context EngineID

icmp optional Boolean

Whether or not to perform ICMP monitoring

Default value: false

icmp_latency_threshold optional Integer

If this is set, then a median latency above this value will put a device into warning status

icmp_loss_threshold optional Integer

If this is set, then a packet loss percentage above this value will put the device into warning status

collect_interface_statistics optional Boolean

Whether or not to collect interface statistics

Default value: false

inventory_model_ids optional Array

An array of inventory model IDs that should have this monitoring template applied to them.

Success 200

Field Type Description
id Number

The ID of the monitoring template.

name String

The name of the monitoring template

inventory_model_ids Array

An array of inventory model IDs that have this monitoring template applied to them.

snmp_version Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id String

If you are using SNMPv3, this is the default context EngineID

icmp Boolean

Whether or not to perform ICMP monitoring

collect_interface_statistics Boolean

Whether or not to collect interface statistics

Default value: false

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Standard CPE Template",
    "snmp_version": 2,
    "snmp_community": "public",
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": false,
    "collect_interface_statistics": true,
    "inventory_model_ids": [
         1,
         2,
         5
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "icmp": "icmp must be a boolean."
     },
     "status_code": 422
   }
 }

Monitoring_Templates - Delete a SNMP OID threshold

Delete a SNMP OID threshold

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

snmp_oid_id Integer

The ID of the SNMP oid

id Integer

The ID of the SNMP OID threshold

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the SNMP OID threshold could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "SNMP OID threshold does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a SNMP OID

Delete a SNMP OID

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

id Integer

The ID of the SNMP OID

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the SNMP OID could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "SNMP OID does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a monitoring graph

Delete a monitoring graph

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

id Integer

The ID of the monitoring graph

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the monitoring graph could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "monitoring graph does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Delete a monitoring template

Delete a monitoring template

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field Type Description
id Number

The ID of the monitoring template

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the monitoring template could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "monitoring template does not exist.",
         "status_code": 404
     }
 }

Monitoring_Templates - Get all SNMP OID thresholds

Get all SNMP OID thresholds.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

snmp_oid_id Integer

The ID of the SNMP oid

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the SNMP OID threshold.

operator String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes Integer

The amount of time that the threshold must be violated before it is triggered

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "operator": "lt",
      "value": 5,
      "time_period_in_minutes": 15
    },
    {
      "id": 1,
      "operator": "gte",
      "value": 15,
      "time_period_in_minutes": 1
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all SNMP OIDs for a template

Get all SNMP OIDs associated with a particular monitoring template.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Number

The ID of the SNMP OID.

name String

The name of the SNMP OID

oid String

The numeric OID

color String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale Boolean

Whether or not results from this OID are automatically scaled by thousands.

display_as_table Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "oid": "1.2.3.4",
      "name": "Test",
      "color": "#3498db",
      "unit_of_measurement": null,
      "monitoring_graph_id": 2,
      "auto_scale": true,
      "display_as_table": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all monitoring graphs

Get all monitoring graphs

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the monitoring graph.

name String

The name of the monitoring graph

type String

The type of graph

stacked Boolean

Whether or not values should be stacked on the graph, or drawn independently

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Aggregate Graph",
      "type": "line",
      "stacked": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get all monitoring templates

Get all monitoring templates

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the monitoring template.

name String

The name of the monitoring template

inventory_model_ids Array

An array of inventory model IDs that have this monitoring template applied to them.

snmp_version Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id String

If you are using SNMPv3, this is the default context EngineID

icmp Boolean

Whether or not to perform ICMP monitoring

collect_interface_statistics Boolean

Whether or not to collect interface statistics

Default value: false

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "name": "My Test Template",
      "snmp_version": 1,
      "snmp_community": "private",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null,
      "icmp": false,
      "icmp_latency_threshold": null,
      "icmp_loss_threshold": null,
      "collect_interface_statistics": false,
      "inventory_model_ids": [
        3
      ]
    },
    {
      "id": 14,
      "name": "MikroTik Probe",
      "snmp_version": 2,
      "snmp_community": "public",
      "snmp3_sec_level": null,
      "snmp3_auth_protocol": null,
      "snmp3_auth_passphrase": null,
      "snmp3_priv_protocol": null,
      "snmp3_priv_passphrase": null,
      "snmp3_context_name": null,
      "snmp3_context_engine_id": null,
      "icmp": true,
      "icmp_latency_threshold": null,
      "icmp_loss_threshold": null,
      "collect_interface_statistics": false,
      "inventory_model_ids": [
           1
      ]
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Monitoring_Templates - Get an individual SNMP OID threshold

Get an individual SNMP OID threshold.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

snmp_oid_id Integer

The ID of the SNMP oid

id Integer

The ID of the SNMP OID threshold

Success 200

Field Type Description
id Integer

The ID of the SNMP OID threshold.

operator String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes Integer

The amount of time that the threshold must be violated before it is triggered

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 12
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual SNMP OID

Get an individual SNMP OID

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

id Integer

The ID of the SNMP OID

Success 200

Field Type Description
id Number

The ID of the SNMP OID.

name String

The name of the SNMP OID

oid String

The numeric OID

color String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale Boolean

Whether or not results from this OID are automatically scaled by thousands.

display_as_table Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

HTTP/1.1 200 OK
{
  "data": {
      "id": 2,
      "oid": "1.2.3.4",
      "name": "Test",
      "color": "#3498db",
      "unit_of_measurement": null,
      "monitoring_graph_id": 2,
      "auto_scale": true,
      "display_as_table": false
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual monitoring graph

Get an individual monitoring graph

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

id Integer

The ID of the monitoring graph

Success 200

Field Type Description
id Integer

The ID of the monitoring graph.

name String

The name of the monitoring graph

type String

The type of graph

stacked Boolean

Whether or not values should be stacked on the graph, or drawn independently

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Get an individual monitoring template

Get an individual monitoring template

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field Type Description
id Number

The ID of the monitoring template

Success 200

Field Type Description
id Number

The ID of the monitoring template.

name String

The name of the monitoring template

inventory_model_ids Array

An array of inventory model IDs that have this monitoring template applied to them.

snmp_version Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id String

If you are using SNMPv3, this is the default context EngineID

icmp Boolean

Whether or not to perform ICMP monitoring

collect_interface_statistics Boolean

Whether or not to collect interface statistics

Default value: false

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "MikroTik Probe",
    "snmp_version": 0,
    "snmp_community": null,
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": true,
    "icmp_latency_threshold": null,
    "icmp_loss_threshold": null,
    "collect_interface_statistics": false,
    "inventory_model_ids": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update SNMP OID threshold

Update an existing SNMP OID threshold.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:snmp_oid_id/snmp_oid_thresholds/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

snmp_oid_id Integer

The ID of the SNMP oid

id Integer

The ID of the SNMP OID threshold

operator optional String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value optional String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes optional Integer

The amount of time that the threshold must be violated before it is triggered

Success 200

Field Type Description
id Integer

The ID of the SNMP OID threshold.

operator String

The operator to use when evaluating the current result against the threshold defined. gt is greater than, gte is greater than or equal to, lt is less than, lte is less than or equal to, eq is equal to and neq is not equal to.

Allowed values: "gt", "gte", "lt", "lte", "eq", "neq"

value String

The value to use for the threshold. If the value is a string, then only eq or neq are allowed as operators.

time_period_in_minutes Integer

The amount of time that the threshold must be violated before it is triggered

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "operator": "lt",
    "value": 5,
    "time_period_in_minutes": 15
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update SNMP OID

Update an existing SNMP OID.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:monitoring_template_id/snmp_oids/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template to add this OID to.

id Integer

The ID of the SNMP OID

name String

A name for the SNMP OID

oid String

A numeric OID

color optional String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement optional String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id optional Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale optional Boolean

Whether or not to automatically scale this OID in thousands.

Default value: false

display_as_table optional Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

Default value: false

Success 200

Field Type Description
id Number

The ID of the SNMP OID.

name String

The name of the SNMP OID

oid String

The numeric OID

color String

A hex color code for the SNMP OID. This will define the color used when graphing this OID.

Default value: #3498db

unit_of_measurement String

The unit of measurement for the SNMP OID (e.g. bytes, %, Fahrenheit.)

monitoring_graph_id Integer

If you want to attach this SNMP OID to a specific monitoring graph, enter the ID here. If this is null, then this OID will be graphed by itself.

auto_scale Boolean

Whether or not results from this OID are automatically scaled by thousands.

display_as_table Boolean

If this is true, this OID will not be graphed, and will instead be displayed in a table. This is also the default display for text based OIDs.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "oid": "1.2.3.4",
    "name": "Test",
    "color": "#3498db",
    "unit_of_measurement": null,
    "monitoring_graph_id": null,
    "auto_scale": false,
    "display_as_table": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update monitoring graph

Update an existing monitoring graph.

https://example.sonar.software/api/v1/monitoring/monitoring_templates/:monitoring_template_id/monitoring_graphs/:id

Parameter

Field Type Description
monitoring_template_id Integer

The ID of the monitoring template

id Integer

The ID of the monitoring graph

name optional String

A name for the monitoring graph

type optional String

The type of graph

Allowed values: "line", "bar", "area"

stacked optional Boolean

Whether or not values should be stacked on the graph, or drawn independently

Default value: false

Success 200

Field Type Description
id Integer

The ID of the monitoring graph.

name String

The name of the monitoring graph

type String

The type of graph

stacked Boolean

Whether or not values should be stacked on the graph, or drawn independently

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "name": "Aggregate Graph",
    "type": "line",
    "stacked": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Monitoring_Templates - Update monitoring template

Update an existing monitoring template.

https://example.sonar.software/api/v1/network/monitoring/monitoring_templates/:id

Parameter

Field Type Description
id Integer

The ID of the monitoring template

name optional String

A name for the monitoring template

snmp_version optional Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community optional String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level optional String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol optional String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase optional String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol optional String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase optional String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name optional String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id optional String

If you are using SNMPv3, this is the default context EngineID

icmp optional Boolean

Whether or not to perform ICMP monitoring

Default value: false

icmp_latency_threshold optional Integer

If this is set, then a median latency above this value will put a device into warning status

icmp_loss_threshold optional Integer

If this is set, then a packet loss percentage above this value will put the device into warning status

collect_interface_statistics optional Boolean

Whether or not to collect interface statistics

Default value: false

inventory_model_ids optional Array

An array of inventory model IDs that should have this monitoring template applied to them.

Success 200

Field Type Description
id Number

The ID of the monitoring template.

name String

The name of the monitoring template

inventory_model_ids Array

An array of inventory model IDs that have this monitoring template applied to them.

snmp_version Integer

Default SNMP queries made using this template to this SNMP version. 2 is version 2c.

Allowed values: 1, 2, 3

snmp_community String

Default SNMP queries made using this template to use this SNMP community. If your snmp_version is 3, then this will be used as the SNMPv3 securityName.

snmp3_sec_level String

If you are using SNMPv3, this is the default security level

Allowed values: "noAuthNoPriv", "authNoPriv", "authPriv"

snmp3_auth_protocol String

If you are using SNMPv3, this is the default authentication protocol

Allowed values: "MD5", "SHA"

snmp3_auth_passphrase String

If you are using SNMPv3, this is the default authentication pass phrase

snmp3_priv_protocol String

If you are using SNMPv3, this is the default privacy protocol

Allowed values: "DES", "AES"

snmp3_priv_passphrase String

If you are using SNMPv3, this is the default privacy passphrase

snmp3_context_name String

If you are using SNMPv3, this is the default context name

snmp3_context_engine_id String

If you are using SNMPv3, this is the default context EngineID

icmp Boolean

Whether or not to perform ICMP monitoring

collect_interface_statistics Boolean

Whether or not to collect interface statistics

Default value: false

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "MikroTik Probe",
    "snmp_version": 2,
    "snmp_community": "somerandomcommunity",
    "snmp3_sec_level": null,
    "snmp3_auth_protocol": null,
    "snmp3_auth_passphrase": null,
    "snmp3_priv_protocol": null,
    "snmp3_priv_passphrase": null,
    "snmp3_context_name": null,
    "snmp3_context_engine_id": null,
    "icmp": true,
    "icmp_latency_threshold": null,
    "icmp_loss_threshold": null,
    "collect_interface_statistics": false,
    "inventory_model_ids": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Network Site IP Addresses

Network_Site_IP_Addresses - Assign an IP to a network site

This endpoint allows you to assign IPv4/IPv6 assignments to a network site or an inventory model field on an network site. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field Type Description
id Number

The ID of the network site

subnet String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within an infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32.

assigned_entity String

The entity to assign this to - the network site directly or an inventory item on the network site.

Allowed values: "network_sites", "inventory_items"

assigned_id optional Number

The ID of the entity referenced in assigned_entity. If assigned_entity is 'network_sites'

inventory_item_field_id optional Number

If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"

description optional String

An optional description for the assignment

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": {
     "id": 53,
     "subnet_id": 4,
     "subnet": "192.168.0.153",
     "assigned_entity": "network_sites",
     "assigned_id": 1,
     "inventory_item_field_id": null,
     "ip_pool_id": 3,
     "network_site_id": 1,
     "description": "Loopback for Router ABC",
     "soft": false
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Network_Site_IP_Addresses - Assign an IP to a network site

This endpoint allows you to assign IPv4/IPv6 assignments to a network site or an inventory model field on an network site. Please see the documentation for more details about the different scenarios in which you would pick each entity.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field Type Description
id Number

The ID of the network site

subnet String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within an infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32.

assigned_entity String

The entity to assign this to - the network site directly or an inventory item on the network site.

Allowed values: "network_sites", "inventory_items"

assigned_id optional Number

The ID of the entity referenced in assigned_entity. If assigned_entity is 'network_sites'

inventory_item_field_id optional Number

If you are assigning this to an inventory item, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.) This is required if assigned_entity is "inventory_items"

description optional String

An optional description for the assignment

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
  "data": {
     "id": 53,
     "subnet_id": 4,
     "subnet": "192.168.0.153",
     "assigned_entity": "network_sites",
     "assigned_id": 1,
     "ip_pool_id": 3,
     "network_site_id": 1,
     "description": "Loopback for Router ABC"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
        "message": "The requested subnet overlaps the existing assignment of 192.168.100.17",
        "status_code": 422
      }
 }

Network_Site_IP_Addresses - Delete IP assignment

Delete an IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the network site

ip_assignment_id Number

The ID of the IP assignment

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the IP assignment could not be deleted

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "message": "That IP assignment is not assigned to that network site."
         },
         "status_code": 422
     }
 }

Network_Site_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the network site

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 52,
      "subnet_id": 4,
      "subnet": "192.168.0.2",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "inventory_item_field_id": null,
      "ip_pool_id": null,
      "network_site_id": 1,
      "description": null,
      "soft": false
    },
    {
      "id": 53,
      "subnet_id": 4,
      "subnet": "192.168.0.153",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "inventory_item_field_id": null,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": null,
      "soft": false
    },
    {
      "id": 54,
      "subnet_id": 4,
      "subnet": "192.168.0.154",
      "assigned_entity": "inventory_items",
      "assigned_id": 3,
      "inventory_item_field_id": null,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": "Some description",
      "soft": false
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_IP_Addresses - Get all IP assignments

Retrieve a list of existing IP assignments on the account.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the network site

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 52,
      "subnet_id": 4,
      "subnet": "192.168.0.2",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "ip_pool_id": null,
      "network_site_id": 1,
      "description": null
    },
    {
      "id": 53,
      "subnet_id": 4,
      "subnet": "192.168.0.153",
      "assigned_entity": "network_sites",
      "assigned_id": 1,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": null
    },
    {
      "id": 54,
      "subnet_id": 4,
      "subnet": "192.168.0.154",
      "assigned_entity": "inventory_items",
      "assigned_id": 3,
      "ip_pool_id": 3,
      "network_site_id": 1,
      "description": "Some description"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the network site

ip_assignment_id Number

The ID of the IP assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.2",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "inventory_item_field_id": null,
    "ip_pool_id": null,
    "network_site_id": 1,
    "description": "Finn & Jake's favorite IP",
    "soft": false
  }
}

Network_Site_IP_Addresses - Get individual IP assignment

Retrieve a specific IP assignment.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the network site

ip_assignment_id Number

The ID of the IP assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.2",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "ip_pool_id": null,
    "network_site_id": 1,
    "description": "Finn & Jake's favorite IP"
  }
}

Network_Site_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an network site, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the network site

ip_assignment_id Number

The ID of the IP assignment

subnet optional String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.

assigned_id optional Number

Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same network site as the existing assignment, it will also be rejected.

inventory_item_field_id optional Number

If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).

description optional String

An optional description for the assignment

make_permanent Boolean

If this is set to true, and the soft property of this IP assignment is currently true, then this will be changed to a permanent assignment.

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

inventory_item_field_id Number

If this IP is assigned to an inventory item MAC/IMSI, this will be the ID of the inventory item field. Otherwise, it will be null.

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

soft Boolean

If this is true, this IP was assigned by Sonar learning about it from an external source (e.g. DHCP server, RADIUS accounting data.)

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.156/32",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "inventory_item_field_id": null,
    "ip_pool_id": 3,
    "network_site_id": 1,
    "description": null,
    "soft": false
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Network_Site_IP_Addresses - Update IP assignment

Update an existing IP assignment. If the assignment is on an network site, only the subnet can be changed. If it is on an inventory item, the assigned_id, the subnet and inventory_item_field_id can be changed. To change the entity on an assignment other than an inventory item, delete the existing assignment and create a new one.

https://example.sonar.software/api/v1/network/network_sites/:id/ip_assignments/:ip_assignment_id

Parameter

Field Type Description
id Number

The ID of the network site

ip_assignment_id Number

The ID of the IP assignment

subnet optional String

The subnet to assign to this entity, with a CIDR prefix, either IPv4 or IPv6. E.g. 192.168.100.1/32 or 2001:DB8::/64. It must fit within a infrastructure/mixed subnet, or an IP pool. IP pool assignments can only be an IPv4 /32s.

assigned_id optional Number

Only valid if this is an inventory item - this will allow you to move the IP to another inventory item. If you supply this, you must also supply inventory_item_field_id or the query will be rejected. If the inventory item is not assigned to the same network site as the existing assignment, it will also be rejected.

inventory_item_field_id optional Number

If you want to change the field ID, supply the ID of the field that contains the MAC address (for DHCP assignment) or the IMSI (for LTE provisioning.).

description optional String

An optional description for the assignment

Success 200

Field Type Description
id Number

The ID of the ip assignment

subnet_id Number

The ID of the subnet

subnet String

The IPv4/IPv6 subnet

assigned_entity String

The type of entity this is assigned to

assigned_id Number

The ID of the entity this is assigned to

ip_pool_id Number

If this falls into an IP pool, the ID of the pool, otherwise, null

network_site_id Number

The ID of the network site the IP is assigned to

description String

An optional description for the assignment

HTTP/1.1 200 OK
{
  "data": {
    "id": 52,
    "subnet_id": 4,
    "subnet": "192.168.0.156/32",
    "assigned_entity": "network_sites",
    "assigned_id": 1,
    "ip_pool_id": 3,
    "network_site_id": 1,
    "description": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "subnet": "abcdefg is not a valid IP address."
         },
         "status_code": 422
     }
 }

Network Site Inventory

Network_Site_Inventory - Get all inventory items

Get a list of inventory at a specific network site.

https://example.sonar.software/api/v1/network/network_sites/:id/inventory_items

Parameter

Field Type Description
id Number

The ID of the network site

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "inventory_model_id": 1,
      "status": "functional",
      "purchase_price": 0,
      "condition": "new",
      "consumed": false,
      "consumed_at": null,
      "fields": [
        {
          "field_id": 1,
          "data": "00:00:00:00:00:0C"
        }
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Site_Inventory - Get individual inventory item

Get a specific inventory item at a specific network site.

https://example.sonar.software/api/v1/network/network_sites/:id/inventory_items/:item_id

Parameter

Field Type Description
id Number

The ID of the network site

item_id Number

The ID of the inventory item

Success 200

Field Type Description
id Number

The ID of the inventory item

inventory_model_id Number

The ID of the model

status String

The status of the device, when inserting this will typically always be 'functional'

Allowed values: "functional", "failed", "lost"

condition String

The condition of the device

consumed Boolean

Whether or not this item has been consumed. If this is not a consumable item, this will always be false.

consumed_at String

If consumed is true, this will be the UTC datetime that it became true in YYYY-MM-DD HH:ii:ss format.

fields Array

An array of fields for this item. The structure is detailed below

field_id Number

The ID of the model field (must be an existing field associated with the inventory_model_id)

data String

The data to input in the field. This field may be restricted to a certain type, you will have to query the inventory model field endpoints to discover this. E.g. it may require a MAC address or a regular expression

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "inventory_model_id": 1,
    "status": "functional",
    "purchase_price": 0,
    "condition": "new",
    "consumed": false,
    "consumed_at": null,
    "fields": [
      {
        "field_id": 1,
        "data": "00:00:00:00:00:0C"
      }
    ]
  }
}

Network Sites

Network_Sites - Create network site address

Create a new network site address

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses

Parameter

Field Type Description
network_site_id Number

The ID of the network site to add the address to

line1 String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

The county, only returned for US states

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 201 OK
{
    "data": {
        "id": 3,
        "line1": "555 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Network_Sites - Create network site

Create a new network site.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field Type Description
name String

A unique name for the network site

line1 optional String

Line1 of the physical address of the site

line2 optional String

Line2 of the physical address of the site

city optional String

The city of the site

state optional String

The state/province of the site

zip optional String

The zip/postal code of the site

country String

The country of the site, as a two digit string

latitude String

The latitude of the site in decimal

longitude String

The longitude of the site in decimal

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

HTTP/1.1 201 OK
{
    "data": {
      "id": 1,
      "name": "My House",
      "height_in_meters": 15
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Create network site

Create a new network site.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field Type Description
name String

A unique name for the network site

line1 optional String

Line1 of the physical address of the site

line2 optional String

Line2 of the physical address of the site

city optional String

The city of the site

state optional String

The state/province of the site

zip optional String

The zip/postal code of the site

country String

The country of the site, as a two digit string

latitude String

The latitude of the site in decimal

longitude String

The longitude of the site in decimal

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

HTTP/1.1 201 OK
{
    "data": {
      "id": 1,
      "name": "My House"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Delete network site address

Delete a network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field Type Description
network_site_id Number

The ID of the network site

address_id Number

The ID of the address

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Address deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the address could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "No item with that ID found.",
         "status_code": 404
     }
 }

Network_Sites - Delete network site

Delete a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the network site

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the network site could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Network site not found.",
         "status_code": 404
     }
 }

Network_Sites - Delete network site

Delete a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the network site

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the network site could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Network site not found.",
         "status_code": 404
     }
 }

Network_Sites - Get all network site addresses

Get a list of the addresses for network site ID :network_site_id

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses

Parameter

Field Type Description
network_site_id Number

The ID of the network site

limit optional Number

The number of entries to return

page optional Number

The page of results to return

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "line1": "12345 Some Ln",
            "line2": "",
            "city": "West Allis",
            "state": "Wisconsin",
            "county": "Milwaukee Co.",
            "zip": "53226",
            "country": "US",
            "latitude": null,
            "longitude": null,
            "address_type_id": 1
        }
    ],
    "paginator": {
        "total_count": 1,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Network_Sites - Get all network sites

Get a list of network sites.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My House",
      "height_in_meters": 100.4
    },
    {
      "id": 2,
      "name": "Jimbob's House of Data",
      "height_in_meters": 50
    },
    {
      "id": 3,
      "name": "Equinix",
      "height_in_meters": 501
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Sites - Get all network sites

Get a list of network sites.

https://example.sonar.software/api/v1/network/network_sites

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "My House"
    },
    {
      "id": 2,
      "name": "Jimbob's House of Data"
    },
    {
      "id": 3,
      "name": "Equinix"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Network_Sites - Get individual network site address

Get an individual network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field Type Description
network_site_id Number

The ID of the network site

address_id Number

The ID of the address

county String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data":
    {
       "line1": "12345 Some Ln",
       "line2": "",
       "city": "West Allis",
       "state": "Wisconsin",
       "county": "Milwaukee Co.",
       "zip": "53226",
       "country": "US",
       "latitude": null,
       "longitude": null,
       "address_type_id": 1
    }
}

Network_Sites - Get individual network site

Get an individual network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the account type

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My House",
      "height_in_meters": 43
    }
}

Network_Sites - Get individual network site

Get an individual network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the account type

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My House"
    }
}

Network_Sites - Update network site address

Update a network site address.

https://example.sonar.software/api/v1/network_sites/:network_site_id/addresses/:address_id

Parameter

Field Type Description
network_site_id Number

The ID of the network site to update the address on

address_id Number

The ID of the address

line1 optional String

The first line of the address

line2 optional String

The second line of the address, typically used for a suite number, apartment number, etc

city optional String

The city

state optional String

The state, province or other country subdivision

county optional String

A valid county for the subdivision obtained from /_data/counties. This is only used for US states and should be null for any other country.

zip optional String

The ZIP/postal code

country optional String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude optional Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude optional Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id optional Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

Success 200

Field Type Description
id Number

The internal ID of the address

line1 String

The first line of the address

line2 String

The second line of the address, typically used for a suite number, apartment number, etc

city String

The city

state String

The state, province or other country subdivision

county String

The county, only returned for US states

zip String

The ZIP/postal code

country String

A valid, two character country code. You can obtain a list of valid country codes from the /_data/countries API endpoint.

latitude Float

The latitude of the address, in decimal. If no latitude is set, this will be null.

longitude Float

The longitude of the address, in decimal. If no longitude is set, this will be null.

address_type_id Number

The type of address this is. You can obtain a list of address types from the /system/address_types API endpoint.

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "line1": "444 Packers Ln",
        "line2": "Suite 1337",
        "city": "Green Bay",
        "state": "Wisconsin",
        "county": "Green Bay Co.",
        "zip": "54332",
        "country": "US",
        "latitude": null,
        "longitude": null,
        "address_type_id": 2
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "address_type_id": "The selected address type id is not valid.",
         },
         "status_code": 422
     }
 }

Network_Sites - Update network site

Update a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the network site

name String

A unique name for the network site

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

height_in_meters Number

The height of the network site, in meters. This is only really used if you're utilizing the path profiling tools in Sonar, or anything related to calculating wireless signals.

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My Data Center",
      "height_in_meters": 12
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Network_Sites - Update network site

Update a network site.

https://example.sonar.software/api/v1/network/network_sites/:id

Parameter

Field Type Description
id Number

The ID of the network site

name String

A unique name for the network site

Success 200

Field Type Description
id Number

The ID of the network site

name String

A descriptive name of the network site

HTTP/1.1 200 OK
{
    "data": {
      "id": 1,
      "name": "My Data Center"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

Notes

Notes - Create note

Create a new note

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Integer

The ID of the entity

category String

A non-localized string representing the category of the note

Allowed values: "inquiry", "billing", "support", "sales", "other"

message String

The content of the note. This may contain HTML

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

Success 200

Field Type Description
id Integer

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude",
    "priority": 0
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That is not a valid entity type for a note."
         },
         "status_code": 422
     }
 }

Notes - Create note

Create a new note

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Number

The ID of the entity

category String

A non-localized string representing the category of the note

Allowed values: "inquiry", "billing", "support", "sales", "other"

message String

The content of the note. This may contain HTML

Success 200

Field Type Description
id Number

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That is not a valid entity type for a note."
         },
         "status_code": 422
     }
 }

Notes - Delete a note

Delete a note.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Integer

The ID of the entity

note_id Integer

The ID of the note

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the alerting rotation day/time could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "alerting rotation day/time does not exist.",
         "status_code": 404
     }
 }

Notes - Get all notes for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Integer

The ID of the entity

limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

Success 200

Field Type Description
id Integer

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "category": "billing",
      "message": "Took a call from Adelaide, she said it was time we got paid. She busted out her VISA because she said the invoice pleased her.",
      "username": "reginald",
      "priority": 0
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Notes - Get all notes for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Number

The ID of the entity

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "category": "billing",
      "message": "Took a call from Adelaide, she said it was time we got paid. She busted out her VISA because she said the invoice pleased her.",
      "username": "reginald"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Notes - Get individual note for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Integer

The ID of the entity

note_id Integer

The ID of the note

Success 200

Field Type Description
id Integer

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude",
    "priority": 1
  }
}

Notes - Get individual note for an entity

Get a list of the notes for an entity, such as an account.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Number

The ID of the entity

note_id Number

The ID of the note

Success 200

Field Type Description
id Number

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "category": "billing",
    "message": "I just found out I can type ANYTHING I want in here!",
    "username": "ermintrude"
  }
}

Notes - Update a note

Update a note.

https://example.sonar.software/api/v1/notes/:entity_type/:entity_id/:note_id

Parameter

Field Type Description
entity_type String

The type of entity. An entity can be anything stored in the system - use the URL for the entity API functions to determine the name. E.g. to store an account note, use 'accounts'. To store a network site note, use 'network_sites'.

entity_id Integer

The ID of the entity

note_id Integer

The ID of the note

category String

The category of the note

Allowed values: "inquiry", "billing", "support", "sales", "other"

message String

The note content

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Allowed values: 0, 1, 2

Success 200

Field Type Description
id Integer

An ID representing the individual note

category String

A non-localized string representing the category of the note

message String

The content of the note. This may contain HTML

username String

The username of the user who created the note

priority optional Integer

The priority of the note. 0 means a regular note. 1 is a sticky note. 2 is an alert note.

Default value: 0

Allowed values: 0, 1, 2

HTTP/1.1 200 OK
{
  "data": {
    "id": 4,
    "category": "inquiry",
    "message": "test",
    "username": "admin",
    "priority": 0
  }
}

Packages

Packages - Create package

Create a new package

https://example.sonar.software/api/v1/system/packages

Parameter

Field Type Description
name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

Success 200

Field Type Description
id Number

The internal ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

Packages - Delete package

Delete a package. This will not remove the services from accounts, it will just prevent the package being used in the future. Since packages have an 'active' flag, it generally makes more sense to set them inactive rather than deleting unless you want to permanently remove it from the interface.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field Type Description
id Number

The ID of the package

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Package deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the package could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Package not found",
         "status_code": 404
     }
 }

Packages - Get all packages

Get a list of the service packages in the system

https://example.sonar.software/api/v1/system/packages

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "active": true,
      "name": "My Awesome Package",
      "services": [
        1,
        5,
        7
      ]
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Packages - Get individual package

Get an individual service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field Type Description
id Number

The ID of the package

Success 200

Field Type Description
id Number

The internal ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Packages - Update package

Update a service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field Type Description
id Number

The ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

Success 200

Field Type Description
id Number

The internal ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

Packages - Update package

Update a service package.

https://example.sonar.software/api/v1/system/packages/:id

Parameter

Field Type Description
id Number

The ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

Success 200

Field Type Description
id Number

The internal ID of the package

name String

A descriptive name of the package

active Boolean

Whether or not this package can still be added to accounts

services Array

An array of service IDs that make up this package

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "My Awesome Package",
    "services": [
      1,
      5,
      7
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "That service ID is not a valid service"
         },
         "status_code": 422
     }
 }

RADIUS Accounts

RADIUS_Accounts - Create a new RADIUS account

Create a new RADIUS account. For this to work, there must be an enabled RADIUS server defined in Sonar.

https://example.sonar.software/api/v1/accounts/:id/radius_accounts

Parameter

Field Type Description
id Number

The ID of the account

username String

The username for the account

password String

The password for the account

create_on_server optional Boolean

Whether or not this account should be created on the RADIUS server. This should generally always be set to true unless you are performing an import and you just need to get Sonar to match what currently exists on the server.

Default value: true

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this RADIUS account with. This will affect the groups it is in, if you have groups that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned.

Success 200

Field Type Description
id Number

The ID of the RADIUS account

username String

The RADIUS account username

password String

The RADIUS account password

service_id Number

The ID of the data service this account is associated with

HTTP/1.1 201 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "goldeneagle",
       "service_id": 2
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
         },
         "status_code": 422
     }
 }

RADIUS_Accounts - Delete RADIUS account

Delete a RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field Type Description
account_id Number

The ID of the account

radius_account_id Number

The ID of the RADIUS account

delete_from_server optional Boolean

Whether or not to delete the account from the remote RADIUS server, or just from Sonar. You should only set this to false if you don't want to manipulate the remote RADIUS server for some reason.

Default value: true

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the RADIUS account could not be deleted

status_code Number

422

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS account does not exist."
         },
         "status_code": 422
     }
 }

RADIUS_Accounts - Get all RADIUS accounts

Get a list of RADIUS accounts.

https://example.sonar.software/api/v1/accounts/:id/radius_accounts

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the account

Success 200

Field Type Description
id Number

The ID of the RADIUS account

username String

The RADIUS account username

password String

The RADIUS account password

HTTP/1.1 200 OK
{
    "data": [
       {
           "id": 1,
           "username": "p_luckey",
           "password": "oculus"
       },
       {
           "id": 2,
           "username": "s_westlake",
           "password": "eaglerare"
       }
    ],
    "paginator": {
        "total_count": 2,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

RADIUS_Accounts - Get individual RADIUS account

Get an individual RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field Type Description
account_id Number

The ID of the account

radius_account_id Number

The ID of the RADIUS account

Success 200

Field Type Description
id Number

The ID of the RADIUS account

username String

The RADIUS account username

password String

The RADIUS account password

service_id Number

The ID of the data service this account is associated with

HTTP/1.1 200 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "goldeneagle",
       "service_id": 2
   }
}

RADIUS_Accounts - Update RADIUS account

Update a RADIUS account.

https://example.sonar.software/api/v1/accounts/:account_id/radius_accounts/:radius_account_id

Parameter

Field Type Description
account_id Number

The ID of the account

radius_account_id Number

The ID of the RADIUS account

username String

The username for RADIUS account

password String

The password for the RADIUS account

update_on_server optional Boolean

Whether or not this account should be updated on the remote RADIUS server, or only in Sonar. The only time you should set this to false is if you are trying to reconcile Sonar with your RADIUS server

Default value: true

service_id optional Number

If the account has multiple data services, you can decide which data service to associate this RADIUS account with. This will affect the groups it is in, if you have groups that are assigned by service. If the account only has one service, you can omit this and it will be automatically assigned.

Success 200

Field Type Description
id Number

The ID of the RADIUS account

username String

The RADIUS account username

password String

The RADIUS account password

service_id Number

The ID of the data service this account is associated with

HTTP/1.1 200 OK
{
    "data": {
       "id": 2,
       "username": "s_westlake",
       "password": "regulareagle",
       "service_id": 2
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken."
         },
         "status_code": 422
     }
 }

RADIUS Groups

RADIUS_Groups - Create a new RADIUS group

Create a new RADIUS group. If there is an enabled RADIUS server in good status in Sonar, this group will immediately be created on it with appropriate accounts associated.

https://example.sonar.software/api/v1/network/provisioning/radius_groups

Parameter

Field Type Description
name String

The name of the RADIUS group

priority Number

The priority for this RADIUS group

delinquent optional Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

Default value: 3

active optional Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

Default value: 3

fall_through optional Boolean

Whether fall-through is enabled or not on this RADIUS group.

Default value: false

account_groups optional Array

An array of account group IDs that are a relation to this RADIUS group.

account_types optional Array

An array of account type IDs that are a relation to this RADIUS group.

services optional Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses optional Array

An array of account status IDs that are a relation to this RADIUS group.

Success 200

Field Type Description
id Number

The ID of the RADIUS group

name String

The name of the RADIUS group

priority Number

The priority for this RADIUS group

delinquent Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

fall_through Boolean

Whether fall-through is enabled or not on this RADIUS group.

account_groups Array

An array of account group IDs that are a relation to this RADIUS group.

account_types Array

An array of account type IDs that are a relation to this RADIUS group.

services Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses Array

An array of account status IDs that are a relation to this RADIUS group.

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The RADIUS group name has already been taken.",
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Create a new reply attribute

Create a new RADIUS group reply attribute. If there is an enabled RADIUS server in good status in Sonar, this attribute will immediately be created on it with appropriate groups associated.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes

Parameter

Field Type Description
attribute String

The attribute name

operator String

The operator for the attribute

Allowed values: "=", ":=", "+="

reply String

The reply value for the attribute

Success 200

Field Type Description
id Number

The ID of the attribute

attribute String

The attribute name

operator String

The operator for the attribute

reply String

The reply value for the attribute

 HTTP/1.1 201 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "Attribute test123 is duplicated. You may only include each attribute once.",
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Delete RADIUS group

Delete a RADIUS group. This will immediately remove the group from your RADIUS server, if it is enabled and in a good status.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field Type Description
id Number

The ID of the RADIUS group.

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the RADIUS group could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS group does not exist."
         },
         "status_code": 404
     }
 }

RADIUS_Groups - Delete reply attribute

Delete a RADIUS group reply attribute.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field Type Description
id Number

The ID of the RADIUS group

attribute_id Number

The ID of the attribute

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the RADIUS reply attribute could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": {
             "message": "RADIUS reply attribute does not exist."
         },
         "status_code": 404
     }
 }

RADIUS_Groups - Get all RADIUS groups

Get a list of RADIUS groups.

https://example.sonar.software/api/v1/network/provisioning/radius_groups

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the RADIUS group

name String

The name of the RADIUS group

priority Number

The priority for this RADIUS group

delinquent Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

fall_through Boolean

Whether fall-through is enabled or not on this RADIUS group.

account_groups Array

An array of account group IDs that are a relation to this RADIUS group.

account_types Array

An array of account type IDs that are a relation to this RADIUS group.

services Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses Array

An array of account status IDs that are a relation to this RADIUS group.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "name": "Delinquent",
      "priority": 1,
      "active": 3,
      "delinquent": 1,
      "fall_through": false,
      "account_groups": [],
      "account_types": [
        2,
        1
      ],
      "services": [],
      "account_statuses": []
    },
    {
      "id": 2,
      "name": "Commercial With Platinum Data Service",
      "priority": 2,
      "active": 3,
      "delinquent": 3,
      "fall_through": true,
      "account_groups": [],
      "account_types": [
        2
      ],
      "services": [
        1
      ],
      "account_statuses": []
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

RADIUS_Groups - Get all reply attributes

Get a list of of attributes for a specific group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes

Parameter

Field Type Description
id Number

The ID of the RADIUS group

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the attribute

attribute String

The attribute name

operator String

The operator for the attribute

reply String

The reply value for the attribute

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "attribute": "Some Other Attribute",
      "operator": "+=",
      "reply": "Some Other Value"
    },
    {
      "id": 2,
      "attribute": "Some Attribute",
      "operator": "=",
      "reply": "Some Value"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

RADIUS_Groups - Get individual RADIUS group

Get an individual RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field Type Description
id Number

The ID of the RADIUS group

Success 200

Field Type Description
id Number

The ID of the RADIUS group

name String

The name of the RADIUS group

priority Number

The priority for this RADIUS group

delinquent Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

fall_through Boolean

Whether fall-through is enabled or not on this RADIUS group.

account_groups Array

An array of account group IDs that are a relation to this RADIUS group.

account_types Array

An array of account type IDs that are a relation to this RADIUS group.

services Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses Array

An array of account status IDs that are a relation to this RADIUS group.

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

RADIUS_Groups - Get individual reply attribute

Get an individual RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field Type Description
id Number

The ID of the RADIUS group

attribute_id Number

The ID of the attribute

Success 200

Field Type Description
id Number

The ID of the attribute

attribute String

The attribute name

operator String

The operator for the attribute

reply String

The reply value for the attribute

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

RADIUS_Groups - Update RADIUS group

Update a RADIUS group.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id

Parameter

Field Type Description
id Number

The ID of the RADIUS group

name optional String

The name of the RADIUS group

priority optional Number

The priority for this RADIUS group

delinquent optional Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

Default value: 3

active optional Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

Default value: 3

fall_through optional Boolean

Whether fall-through is enabled or not on this RADIUS group.

Default value: false

account_groups optional Array

An array of account group IDs that are a relation to this RADIUS group.

account_types optional Array

An array of account type IDs that are a relation to this RADIUS group.

services optional Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses optional Array

An array of account status IDs that are a relation to this RADIUS group.

Success 200

Field Type Description
id Number

The ID of the RADIUS group

name String

The name of the RADIUS group

priority Number

The priority for this RADIUS group

delinquent Number

If this is 1, the group is only applied to delinquent accounts. If this is 2, it is only applied to accounts that are not delinquent. If it is 3, delinquency is not checked.

active Number

If this is 1, the group is only applied to accounts with an active status. If this is 2, it is only applied to accounts that have a non-active status. If it is 3, the active flag on the status is not checked.

fall_through Boolean

Whether fall-through is enabled or not on this RADIUS group.

account_groups Array

An array of account group IDs that are a relation to this RADIUS group.

account_types Array

An array of account type IDs that are a relation to this RADIUS group.

services Array

An array of data service IDs that are a relation to this RADIUS group.

account_statuses Array

An array of account status IDs that are a relation to this RADIUS group.

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "name": "My Group Name?",
    "priority": 15,
    "active": 3,
    "delinquent": 2,
    "fall_through": true,
    "account_groups": [],
    "account_types": [
      1
    ],
    "services": [
      2,
      1
    ],
    "account_statuses": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken."
         },
         "status_code": 422
     }
 }

RADIUS_Groups - Update reply attribute

Update a RADIUS group reply attribute.

https://example.sonar.software/api/v1/network/provisioning/radius_groups/:id/attributes/:attribute_id

Parameter

Field Type Description
id Number

The ID of the RADIUS group

attribute_id Number

The ID of the attribute

attribute optional String

The attribute name

operator optional String

The operator for the attribute

Allowed values: "=", ":=", "+="

reply optional String

The reply value for the attribute

Success 200

Field Type Description
id Number

The ID of the attribute

attribute String

The attribute name

operator String

The operator for the attribute

reply String

The reply value for the attribute

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 3,
    "attribute": "Some Other Attribute",
    "operator": "+=",
    "reply": "Some Other Value"
  }
}

Rate Centers

Rate_Centers - Create a new rate center

Create a new rate center. A rate center is used to store DIDs for voice services.

https://example.sonar.software/api/v1/system/voice/rate_centers

Parameter

Field Type Description
name String

A name for the rate center

Success 200

Field Type Description
id Number

The ID of the rate center.

name String

The name of the rate center

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "My rate center",
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Rate_Centers - Delete a rate center

Delete a rate center

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field Type Description
id Number

The ID of the rate center

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the rate center could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Rate center does not exist.",
         "status_code": 404
     }
 }

Rate_Centers - Get all rate centers

Get all rate centers

https://example.sonar.software/api/v1/system/voice/rate_centers

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the rate center.

name String

The name of the rate center

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "My rate center"
    },
    {
      "id": 1,
      "name": "Another rate center"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Rate_Centers - Get an individual rate center

Get an individual rate center

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field Type Description
id Number

The ID of the rate center

Success 200

Field Type Description
id Number

The ID of the rate center.

name String

The name of the rate center

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "ABC123"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Rate_Centers - Update rate center

Update an existing rate center.

https://example.sonar.software/api/v1/system/voice/rate_centers/:id

Parameter

Field Type Description
id Number

The rate center ID

name optional String

The name of the rate center

Success 200

Field Type Description
id Number

The ID of the rate center.

name String

The name of the rate center

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "My updated name"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Roles

Roles - Get all roles

Get a list of roles from within Sonar.

https://example.sonar.software/api/v1/roles/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the role

name String

The name of the role

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 2,
            "name": "Read Only"
        },
        {
            "id": 3,
            "name": "Network Support"
        },
        {
            "id": 1,
            "name": "Super Admin"
        }
    ],
    "paginator": {
        "total_count": 3,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

Roles - Get individual role

Get data on an Get individual role.

https://example.sonar.software/api/v1/roles/:id
curl -i https://example.sonar.software/api/v1/roles/1

Parameter

Field Type Description
id Number

The id of the role

Success 200

Field Type Description
id Number

The internal id of the role

name String

The name of the role

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Super Admin"
    }
}

Scheduled Events

Scheduled_Events - Create a new scheduled event

Create a new scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field Type Description
account_id Integer

The ID of the account

event_type String

The type of scheduled event this is

Allowed values: "add_service", "remove_service", "change_status", "price_override_service", "remove_price_override_from_service", "add_package", "remove_package"

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)

primary_value String

The primary value for the event. The primary value corresponds to the event. For add_service, it is the service ID to add to the account. For remove_service, it is the unique_service_relationship_id for the service currently on the account. For change_status, it is the ID of the account status to change the account to. For price_override_service, it is the unique_service_relationship_id for the service on the account that you want to price override. For remove_price_override_from_service, it is the unique_service_relationship_id for the service you want to remove the price override from.

secondary_value optional String

The secondary value for the event. This is currently only used for the event price_override_service, and it is the amount, as a decimal, that you want to price override the service to.

proration_override optional Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is false, the system default price override selection will be used.

Default value: false

prorate optional Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true, and can only be set if you have account superuser permissions.

Default value: false

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "scheduled_datetime": "The scheduled datetime cannot be in the past."
     },
     "status_code": 422
   }
 }

Scheduled_Events - Create a new scheduled event

Create a new scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field Type Description
account_id Integer

The ID of the account

event_type String

The type of scheduled event this is

Allowed values: "add_service", "remove_service", "change_status", "price_override_service", "remove_price_override_from_service"

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)

primary_value String

The primary value for the event. The primary value corresponds to the event. For add_service, it is the service ID to add to the account. For remove_service, it is the unique_service_relationship_id for the service currently on the account. For change_status, it is the ID of the account status to change the account to. For price_override_service, it is the unique_service_relationship_id for the service on the account that you want to price override. For remove_price_override_from_service, it is the unique_service_relationship_id for the service you want to remove the price override from.

secondary_value optional String

The secondary value for the event. This is currently only used for the event price_override_service, and it is the amount, as a decimal, that you want to price override the service to.

proration_override optional Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is false, the system default price override selection will be used.

Default value: false

prorate optional Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true, and can only be set if you have account superuser permissions.

Default value: false

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "scheduled_datetime": "The scheduled datetime cannot be in the past."
     },
     "status_code": 422
   }
 }

Scheduled_Events - Delete a scheduled event

Delete a scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the scheduled event

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the scheduled event could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "scheduled event does not exist.",
         "status_code": 404
     }
 }

Scheduled_Events - Get all scheduled events

Get all scheduled events

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

account_id Integer

The ID of the account to get events for

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "event_type": "add_service",
      "scheduled_datetime": "2016-10-25 07:00:00",
      "primary_value": "1",
      "secondary_value": null,
      "proration_override": false,
      "prorate": false,
      "completed": false,
      "user_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Scheduled_Events - Get all scheduled events

Get all scheduled events

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

account_id Integer

The ID of the account to get events for

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "event_type": "add_service",
      "scheduled_datetime": "2016-10-25 07:00:00",
      "primary_value": "1",
      "secondary_value": null,
      "proration_override": false,
      "prorate": false,
      "completed": false,
      "user_id": 1
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Scheduled_Events - Get an individual scheduled event

Get an individual scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field Type Description
account_id Integer

The ID of the account to get events for

id Integer

The ID of the scheduled event

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Get an individual scheduled event

Get an individual scheduled event

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field Type Description
account_id Integer

The ID of the account to get events for

id Integer

The ID of the scheduled event

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "event_type": "add_service",
    "scheduled_datetime": "2016-10-25 07:00:00",
    "primary_value": "1",
    "secondary_value": null,
    "proration_override": false,
    "prorate": false,
    "completed": false,
    "user_id": 1
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Update scheduled event

Update an existing scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the scheduled event

event_type String

The type of scheduled event this is

Allowed values: "add_service", "remove_service", "change_status", "price_override_service", "remove_price_override_from_service", "add_package", "remove_package"

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)

primary_value String

The primary value for the event. The primary value corresponds to the event. For add_service, it is the service ID to add to the account. For remove_service, it is the unique_service_relationship_id for the service currently on the account. For change_status, it is the ID of the account status to change the account to. For price_override_service, it is the unique_service_relationship_id for the service on the account that you want to price override. For remove_price_override_from_service, it is the unique_service_relationship_id for the service you want to remove the price override from. For add_package, it is the package ID. For remove_package it is the unique_package_id from the account to service relationship.

secondary_value optional String

The secondary value for the event. This is currently only used for the event price_override_service, and it is the amount, as a decimal, that you want to price override the service to.

proration_override optional Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is false, the system default price override selection will be used.

prorate optional Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true, and can only be set if you have account superuser permissions.

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Scheduled_Events - Update scheduled event

Update an existing scheduled event.

https://example.sonar.software/api/v1/accounts/:account_id/scheduled_events/:id

Parameter

Field Type Description
account_id Integer

The ID of the account

id Integer

The ID of the scheduled event

event_type String

The type of scheduled event this is

Allowed values: "add_service", "remove_service", "change_status", "price_override_service", "remove_price_override_from_service"

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC (YYYY-MM-DD HH:mm:ss format, in 24 hour time.)

primary_value String

The primary value for the event. The primary value corresponds to the event. For add_service, it is the service ID to add to the account. For remove_service, it is the unique_service_relationship_id for the service currently on the account. For change_status, it is the ID of the account status to change the account to. For price_override_service, it is the unique_service_relationship_id for the service on the account that you want to price override. For remove_price_override_from_service, it is the unique_service_relationship_id for the service you want to remove the price override from.

secondary_value optional String

The secondary value for the event. This is currently only used for the event price_override_service, and it is the amount, as a decimal, that you want to price override the service to.

proration_override optional Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event, and can only be set if you have account superuser permissions. If this is false, the system default price override selection will be used.

prorate optional Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true, and can only be set if you have account superuser permissions.

Success 200

Field Type Description
id Integer

The ID of the scheduled event.

event_type String

The type of scheduled event this is

scheduled_datetime DateTime

The scheduled date and time for this event to occur, in UTC

primary_value String

The primary value for the event

secondary_value String

The secondary value for the event

proration_override Boolean

Whether or not to override the default system proration for this event. Only valid if proration is valid for this event.

prorate Boolean

Whether or not to prorate this event, if proration is valid. This value is only checked if proration_override is true

completed Boolean

Whether or not the job has been completed

user_id Integer

The ID of the user that created this event

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules

Schedules - Create a new schedule blocker

Create a new schedule blocker.

https://example.sonar.software/api/v1/scheduling/schedule_blockers

Parameter

Field Type Description
name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

Success 200

Field Type Description
id Integer

The ID of the blocker

name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

HTTP/1.1 201 OK
{
  "data": {
     "id": 2,
     "name": "brunch",
     "sunday": false,
     "monday": true,
     "tuesday": false,
     "wednesday": false,
     "thursday": false,
     "friday": false,
     "saturday": false,
     "start_timestamp": "13:55",
     "end_timestamp": "14:30",
     "user_ids": [
       1
     ],
     "start": "2017-01-01",
     "weeks": 1,
     "repetitions": 1,
     "infinite_repetitions": true
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "infinite_repetitions": "Infinite repetitions must be a boolean."
     },
     "status_code": 422
   }
 }

Schedules - Create a new schedule day/time

Create a new schedule day/time. A schedule day and time is contained within a schedule, so you must create a schedule first.

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days

Parameter

Field Type Description
schedule_id Number

The ID of the schedule that contains this day/time

day Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp Time

The starting time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

end_timestamp Time

The ending time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

Success 200

Field Type Description
id Number

The ID of the schedule day/time.

day Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

start_timestamp Time

The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

end_timestamp Time

The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "day": 1,
    "start_timestamp": "13:45:00",
    "end_timestamp": "17:00:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "day": "The day must be between 0 and 6."
     },
     "status_code": 422
   }
 }

Schedules - Create a new schedule

Create a new schedule. A schedule is a container for availability, or lack thereof. You must add days to the schedule for it to have any purpose.

https://example.sonar.software/api/v1/scheduling/schedules

Parameter

Field Type Description
name String

A name for the schedule

user_ids Array

An array of user IDs that this schedule is applied to

job_type_ids Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container.

start Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available Boolean

Whether this schedule defines availability, or lack of availability. A schedule with available set to false will always override another schedule with available set to true.

infinite_repetitions Boolean

Set this to true if you want this schedule to run indefinitely

repetitions Number

How many times this schedule should repeat. 0 to never repeat.

weeks Number

How often the repetition should occur, in weeks. If this is 1, this schedule repeats every week. If this is 2, the schedule runs for one week, then breaks for one week, then runs for one week, then breaks for one week, etc. If this is 3, the schedule runs for one week, then breaks for two weeks, then runs for one week, then breaks for two weeks, etc. This interacts with repetitions by repeating repetitions times for the number of active weeks. For example, if weeks is 2, and repetitions is 1, this schedule would run for a week, skip a week, run for a week, and then stop.

Success 200

Field Type Description
id Number

The ID of the schedule.

name String

The name of the schedule

user_ids Array

An array of user IDs that this schedule is applied to

job_type_ids Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container

start Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available Boolean

Whether this schedule defines availability, or lack of availability.

infinite_repetitions Boolean

Will be true if this schedule runs indefinitely

repetitions Number

How many times this schedule should repeat.

weeks Number

How often the repetition should occur, in weeks.

HTTP/1.1 201 OK
{
  "data": {
    "id": 6,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": false,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "That user does not exist."
     },
     "status_code": 422
   }
 }

Schedules - Create a new scheduled time off

Create a new scheduled time off. This is typically used to block out a span of time when an employee is unavailable, for example, during vacation.

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs

Parameter

Field Type Description
user_id Integer

The ID of the user that has time off scheduled

start_time DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time DateTime

The day and time that the user has scheduled off, in the system timezone.

name String

A description/reason for the time off.

Success 200

Field Type Description
user_id Integer

The ID of the user that has time off scheduled

start_time DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time DateTime

The day and time that the user has scheduled off, in the system timezone.

name String

A description/reason for the time off.

id Number

The ID of the scheduled time off.

HTTP/1.1 201 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 01:30:00"
    "name": "test"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Schedules - Delete a schedule blocker

Delete a schedule blocker

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field Type Description
id Integer

The ID of the schedule blocker

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the schedule blocker could not be deleted

status_code Integer

4x

HTTP/1.1 404
 {
     "error": {
         "message": "schedule blocker does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a schedule day/time

Delete a schedule day/time

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field Type Description
schedule_id Number

The ID of the schedule that contains this day/time

id Number

The ID of the schedule day/time

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the schedule day/time could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a schedule

Delete a schedule

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field Type Description
id Number

The ID of the schedule

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the schedule could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Schedule does not exist.",
         "status_code": 404
     }
 }

Schedules - Delete a scheduled time off

Delete a scheduled time off

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field Type Description
id Number

The ID of the scheduled time off

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the scheduled time off could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "scheduled time off does not exist.",
         "status_code": 404
     }
 }

Schedules - Get all schedule blockers

Get all schedule blockers

https://example.sonar.software/api/v1/scheduling/schedule_blockers

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the blocker

name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Brunch",
      "sunday": false,
      "monday": true,
      "tuesday": false,
      "wednesday": false,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "13:55",
      "end_timestamp": "14:30",
      "user_ids": [
        1
      ],
      "start": "2017-01-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 7,
      "name": "Lunch",
      "sunday": false,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "00:00",
      "end_timestamp": "00:45",
      "user_ids": [
        1
      ],
      "start": "2017-02-02",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 8,
      "name": "Dinner",
      "sunday": false,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": false,
      "friday": false,
      "saturday": false,
      "start_timestamp": "00:00",
      "end_timestamp": "00:30",
      "user_ids": [
        1
      ],
      "start": "2017-02-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    },
    {
      "id": 9,
      "name": "Breakfast",
      "sunday": true,
      "monday": true,
      "tuesday": true,
      "wednesday": true,
      "thursday": true,
      "friday": true,
      "saturday": true,
      "start_timestamp": "00:30",
      "end_timestamp": "11:00",
      "user_ids": [],
      "start": "2017-02-01",
      "weeks": 1,
      "repetitions": 1,
      "infinite_repetitions": true
    }
  ],
  "paginator": {
    "total_count": 4,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all scheduled time offs

Get all scheduled time offs

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs

Parameter

Field Type Description
limit optional Integer

The number of entries to return

page optional Integer

The page of results to return

Success 200

Field Type Description
id Integer

The ID of the scheduled time off.

user_id Integer

The ID of the user that has time off scheduled

start_time DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time DateTime

The day and time that the user has scheduled off, in the system timezone.

name String

A description/reason for the time off.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "user_id": 9,
      "start_time": "2016-10-18 21:00:00",
      "end_time": "2016-10-18 22:00:00",
      "name": "Matt's Vacation"
    },
    {
      "id": 3,
      "user_id": 9,
      "start_time": "2016-10-18 01:00:00",
      "end_time": "2016-10-20 19:45:00",
      "name": "Really long dentist appointment"
    },
    {
      "id": 6,
      "user_id": 1,
      "start_time": "2016-10-19 00:00:00",
      "end_time": "2016-10-19 23:45:00",
      "name": "Just a block of time off for user ID 1"
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all schedules

Get all schedules

https://example.sonar.software/api/v1/scheduling/schedules

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the schedule.

name String

The name of the schedule

user_ids Array

An array of user IDs that this schedule is applied to

job_type_ids Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container

start Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available Boolean

Whether this schedule defines availability, or lack of availability.

infinite_repetitions Boolean

Will be true if this schedule runs indefinitely

repetitions Number

How many times this schedule should repeat.

weeks Number

How often the repetition should occur, in weeks.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "user_ids": [ 1 ],
      "job_type_ids": [ 1 ],
      "name": "Commercial Installs",
      "start": "2016-08-05",
      "available": true,
      "infinite_repetitions": false,
      "repetitions": 90,
      "weeks": 1
    },
    {
      "id": 4,
      "user_ids": [ 2, 3 ],
      "name": "Residential Installs",
      "start": "2016-08-05",
      "available": true,
      "infinite_repetitions": true,
      "repetitions": 1,
      "weeks": 3
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get all schedule day/times

Get all schedule day/times

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days

Parameter

Field Type Description
schedule_id Number

The ID of the schedule

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the schedule day/time.

day Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

start_timestamp Time

The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

end_timestamp Time

The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 3,
      "day": 1,
      "start_timestamp": "08:00",
      "end_timestamp": "12:00"
    },
    {
      "id": 6,
      "day": 1,
      "start_timestamp": "20:00",
      "end_timestamp": "22:00"
    },
    {
      "id": 7,
      "day": 1,
      "start_timestamp": "00:00",
      "end_timestamp": "08:00"
    },
    {
      "id": 8,
      "day": 1,
      "start_timestamp": "10:00",
      "end_timestamp": "12:00"
    },
    {
      "id": 9,
      "day": 1,
      "start_timestamp": "00:00",
      "end_timestamp": "23:00"
    }
  ],
  "paginator": {
    "total_count": 5,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Schedules - Get an individual schedule blocker

Get an individual schedule blocker

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field Type Description
id Integer

The ID of the schedule blocker

Success 200

Field Type Description
id Integer

The ID of the blocker

name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "brunch",
    "sunday": false,
    "monday": true,
    "tuesday": false,
    "wednesday": false,
    "thursday": false,
    "friday": false,
    "saturday": false,
    "start_timestamp": "13:55",
    "end_timestamp": "14:30",
    "user_ids": [
      1
    ],
    "start": "2017-01-01",
    "weeks": 1,
    "repetitions": 1,
    "infinite_repetitions": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual schedule day/time

Get an individual schedule day/time

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field Type Description
schedule_id Number

The ID of the schedule that contains this day/time

id Number

The ID of the schedule day/time

Success 200

Field Type Description
id Number

The ID of the schedule day/time.

day Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

start_timestamp Time

The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

end_timestamp Time

The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

HTTP/1.1 200 OK
{
  "data": {
     "id": 9,
     "day": 1,
     "start_timestamp": "00:00",
     "end_timestamp": "23:00"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual schedule

Get an individual schedule

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field Type Description
id Number

The ID of the schedule

Success 200

Field Type Description
id Number

The ID of the schedule.

name String

The name of the schedule

user_ids Array

An array of user IDs that this schedule is applied to

job_type_ids Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container

start Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available Boolean

Whether this schedule defines availability, or lack of availability.

infinite_repetitions Boolean

Will be true if this schedule runs indefinitely

repetitions Number

How many times this schedule should repeat.

weeks Number

How often the repetition should occur, in weeks.

HTTP/1.1 200 OK
{
  "data": {
    "id": 3,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1, 2 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": false,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get an individual scheduled time off

Get an individual scheduled time off

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field Type Description
id Integer

The ID of the scheduled time off

Success 200

Field Type Description
id Integer

The ID of the scheduled time off.

user_id Integer

The ID of the user that has time off scheduled

start_time DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time DateTime

The day and time that the user has scheduled off, in the system timezone.

name String

A description/reason for the time off.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 01:30:00"
    "name": "test"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Get the calculated schedule for a date range

This function will calculate out the availability for all scheduled users, between :start_date and :end_date. It will also include all jobs scheduled within those times. This is a fairly complex data structure that is designed to be used to allow easier integration into external display/scheduling systems.

https://example.sonar.software/api/v1/scheduling/calculated_schedule/:start_date/:end_date

Parameter

Field Type Description
start_date Date

The start date for this query, in the system timezone.

end_date Date

The end date for this query, in the system timezone.

Success 200

Field Type Description
Schedule Array

The format of the data is shown below. The first property is the date. Within that object, the properties are the user IDs. Within the user object, there is a schedule array, a jobs array, and a schedule_blockers array. The schedule array contains a list of available time for the date referenced at the top level, where the property is the job type ID the times are for, and the value is an array of times. The jobs array contains a list of jobs scheduled for that day, formatted in the same manner as jobs queried from the jobs endpoint. The schedule_blockers array contains objects that represent configured schedule blockers. These show the start and end time for the blocker, the name, and the schedule blocker ID. If the blocker has been overridden, then the overridden property will be true. The uniqueid property within this object is just a way for you to uniquely identify blockers in an external application if needed, and can otherwise be ignored.

 HTTP/1.1 200 OK
 {
  "data": {
    "2017-02-06": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "23:59"
            }
          ]
        },
        "jobs": [
          {
            "id": 2,
            "scheduled_datetime": "2017-02-06 12:53",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 5,
            "scheduled_datetime": "2017-02-06 17:43",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 35,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 4,
            "scheduled_datetime": "2017-02-06 08:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 35,
            "notes": "",
            "status": "scheduled",
            "user_ids": [
              1
            ],
            "created_by_user_id": 1,
            "checked_in_users": [],
            "services": []
          }
        ],
        "schedule_blockers": [
          {
            "start": "10:30",
            "end": "11:30",
            "name": "Brunch",
            "id": 2,
            "overridden": true,
            "uniqueid": "2_1"
          },
          {
            "start": "00:00",
            "end": "00:45",
            "name": "Break",
            "id": 7,
            "overridden": false,
            "uniqueid": "7_1"
          },
          {
            "start": "00:00",
            "end": "00:30",
            "name": "Lunch",
            "id": 8,
            "overridden": false,
            "uniqueid": "8_1"
          }
        ]
      }
    },
    "2017-02-07": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "23:59"
            }
          ]
        },
        "jobs": [],
        "schedule_blockers": [
          {
            "start": "00:00",
            "end": "00:45",
            "name": "Break",
            "id": 7,
            "overridden": false,
            "uniqueid": "7_1"
          },
          {
            "start": "00:00",
            "end": "00:30",
            "name": "Lunch",
            "id": 8,
            "overridden": false,
            "uniqueid": "8_1"
          }
        ]
      }
    }
  }
}

Error 4xx

Name Type Description
message String

A reason as to why the schedule day/time could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Get the calculated schedule for a date range

This function will calculate out the availability for all scheduled users, between :start_date and :end_date. It will also include all jobs scheduled within those times. This is a fairly complex data structure that is designed to be used to allow easier integration into external display/scheduling systems.

https://example.sonar.software/api/v1/scheduling/calculated_schedule/:start_date/:end_date

Parameter

Field Type Description
start_date Date

The start date for this query, in the system timezone.

end_date Date

The end date for this query, in the system timezone.

Success 200

Field Type Description
Schedule Array

The format of the data is shown below. The first property is the date. Within that object, the properties are the user IDs. Within the user object, there is a schedule array and a jobs array. The schedule array contains a list of available time for the date referenced at the top level, where the property is the job type ID the times are for, and the value is an array of times. The jobs array contains a list of jobs scheduled for that day, formatted in the same manner as jobs queried from the jobs endpoint.

 HTTP/1.1 200 OK
 {
  "data": {
    "2016-08-21": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-22": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      }
    },
    "2016-08-26": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "04:00",
              "end": "10:00"
            },
            {
              "start": "15:00",
              "end": "21:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "04:00",
              "end": "10:00"
            },
            {
              "start": "15:00",
              "end": "21:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-28": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "01:00"
            }
          ],
          "2": []
        },
        "jobs": []
      }
    },
    "2016-08-29": {
      "1": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": []
      },
      "2": {
        "schedule": {
          "1": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ],
          "2": [
            {
              "start": "00:00",
              "end": "21:00"
            }
          ]
        },
        "jobs": [
          {
            "id": 31,
            "scheduled_datetime": "2016-08-29 11:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "drive_time_in_minutes": 0,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "Please replace the router.",
            "status": "scheduled",
            "user_ids": [
              2
            ],
            "created_by_user_id": 0,
            "checked_in_users": [],
            "services": []
          },
          {
            "id": 32,
            "scheduled_datetime": "2016-08-29 10:00",
            "job_type_id": 1,
            "length_in_minutes": 60,
            "drive_time_in_minutes": 0,
            "ticket_id": null,
            "assigned_type": "accounts",
            "assigned_id": 1,
            "notes": "Please replace the switch.",
            "status": "scheduled",
            "user_ids": [
              2
            ],
            "created_by_user_id": 0,
            "checked_in_users": [],
            "services": []
          }
        ]
      }
    }
  }
}

Error 4xx

Name Type Description
message String

A reason as to why the schedule day/time could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "schedule day/time does not exist.",
         "status_code": 404
     }
 }

Schedules - Override a schedule blocker

Override a schedule blocker for a single user

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id/schedule_blocker_overrides

Parameter

Field Type Description
id Integer

The ID of the blocker

date Date

The date you wish to override the blocker for

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_id Integer

The ID of the user you wish to override the blocker time for

Success 200

Field Type Description
id Integer

The ID of the blocker

date Date

The date you wish to override the blocker for

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_id Integer

The ID of the user you wish to override the blocker time for

HTTP/1.1 200 OK
{
  "data": {
    "date": "2017-02-06",
    "start_timestamp": "10:30",
    "end_timestamp": "11:30",
    "user_id": "1",
    "schedule_blocker_id": 2
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule blocker

Update an existing schedule blocker.

https://example.sonar.software/api/v1/scheduling/schedule_blockers/:id

Parameter

Field Type Description
id Integer

The ID of the blocker

name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

Success 200

Field Type Description
id Integer

The ID of the blocker

name String

A name for the schedule blocker

sunday Boolean

true if this schedule blocks on Sunday, false if not

monday Boolean

true if this schedule blocks on Monday, false if not

tuesday Boolean

true if this schedule blocks on Tuesday, false if not

wednesday Boolean

true if this schedule blocks on Wednesday, false if not

thursday Boolean

true if this schedule blocks on Thursday, false if not

friday Boolean

true if this schedule blocks on Friday, false if not

saturday Boolean

true if this schedule blocks on Saturday, false if not

start_timestamp Time

The start of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

end_timestamp Time

The end of the blocker, expressed as H:m where H is in 24 hour time, and m is minutes (e.g. 13:40)

user_ids Array

An array of user IDs that this blocker should apply to

start Date

The start date for this blocker

weeks Integer

The frequency of repetition for this blocker. If this is 1, it repeats weekly. If this is 2, it repeats every other week.

repetitions Integer

How many times this blocker repeats. Ignored if infinite_repetitions is true

infinite_repetitions Boolean

If this is true, this blocker repeats forever

HTTP/1.1 200 OK
{
  "data": {
    "id": 2
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Integer

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule day/time

Update an existing schedule day/time.

https://example.sonar.software/api/v1/scheduling/schedules/:schedule_id/schedule_days/:id

Parameter

Field Type Description
schedule_id Number

The ID of the schedule that contains this day/time

id Number

The schedule day/time ID

day optional Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

Allowed values: 0, 1, 2, 3, 4, 5, 6

start_timestamp optional Time

The starting time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

end_timestamp optional Time

The ending time for this particular period, in Hour:Minute format, where minute must be in 15 minute increments. This is in the Sonar timezone, not UTC.

Success 200

Field Type Description
id Number

The ID of the schedule day/time.

day Number

The day of the week for this scheduled day/time, where 0 is Sunday and 6 is Saturday.

start_timestamp Time

The starting time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

end_timestamp Time

The ending time for this particular period, in Hour:Minute format. This is in the Sonar timezone, not UTC.

HTTP/1.1 201 OK
{
  "data": {
     "id": 9,
     "day": 1,
     "start_timestamp": "00:00",
     "end_timestamp": "23:00"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update schedule

Update an existing schedule.

https://example.sonar.software/api/v1/scheduling/schedules/:id

Parameter

Field Type Description
name optional String

A name for the schedule

user_ids optional Array

An array of user IDs that this schedule is applied to

job_type_ids optional Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container

start optional Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available optional Boolean

Whether this schedule defines availability, or lack of availability. A schedule with available set to false will always override another schedule with available set to true.

infinite_repetitions optional Boolean

Set this to true if you want this schedule to run indefinitely

repetitions optional Number

How many times this schedule should repeat. 0 to never repeat. You can set this to a high number to repeat indefinitely (e.g. 2147483647)

weeks optional Number

How often the repetition should occur, in weeks. If this is 1, this schedule repeats every week. If this is 2, the schedule runs for one week, then breaks for one week, then runs for one week, then breaks for one week, etc. If this is 3, the schedule runs for one week, then breaks for two weeks, then runs for one week, then breaks for two weeks, etc. This interacts with repetitions by repeating repetitions times for the number of active weeks. For example, if weeks is 2, and repetitions is 1, this schedule would run for a week, skip a week, run for a week, and then stop.

Success 200

Field Type Description
id Number

The ID of the schedule.

name String

The name of the schedule

user_ids Array

An array of user IDs that this schedule is applied to

job_type_ids Array

An array of job type IDs that this time is for. Only jobs with this job type will be allowed to be scheduled in this container

start Date

The date that the schedule should start to be applied, in the local system timezone. YYYY-MM-DD format.

available Boolean

Whether this schedule defines availability, or lack of availability.

infinite_repetitions Boolean

Will be true if this schedule runs indefinitely

repetitions Number

How many times this schedule should repeat.

weeks Number

How often the repetition should occur, in weeks.

HTTP/1.1 200 OK
{
  "data": {
    "id": 6,
    "user_ids": [ 1 ],
    "job_type_ids": [ 1, 2, 3 ],
    "name": "Test",
    "start": "2016-08-05",
    "available": true,
    "infinite_repetitions": true,
    "repetitions": 1,
    "weeks": 3
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Schedules - Update scheduled time off

Update an existing scheduled time off.

https://example.sonar.software/api/v1/scheduling/scheduled_time_offs/:id

Parameter

Field Type Description
user_id optional Integer

The ID of the user that has time off scheduled

start_time optional DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time optional DateTime

The day and time that the user has scheduled off, in the system timezone.

name optional String

A description/reason for the time off.

Success 200

Field Type Description
id Integer

The ID of the scheduled time off.

user_id Integer

The ID of the user that has time off scheduled

start_time DateTime

The day and time that the user has scheduled off, in the system timezone.

end_time DateTime

The day and time that the user has scheduled off, in the system timezone.

name String

A description/reason for the time off.

HTTP/1.1 200 OK
{
  "data": {
    "id": 10,
    "user_id": 1,
    "start_time": "2016-11-01 01:00:00",
    "end_time": "2016-11-01 02:00:00",
    "name": "Update me"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Services

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
id optional Integer

The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups optional Array

An array of account group IDs

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups Array

An array of account group IDs

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null,
         "account_groups": []
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
id optional Integer

The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
id optional Integer

The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $60, but only $35 of it is taxable, set this to 25 (60-35 = 25.) Should be omitted in cases where the entirety of the service is taxable.

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service to exempt from taxation

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, overage, or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment", "overage"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

HTTP/1.1 201 OK
{
    "data": {
         "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "active": true,
    "name": "Schumm Ltd",
    "type": "recurring",
    "application": "debit",
    "amount": 63.62,
    "times_to_run": 4,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [],
    "roles": [],
    "data_service": true,
    "upload_in_kilobits": 500,
    "download_in_kilobits": 1000,
    "technology_code": 70
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Create service

Create a new service

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring or recurring, defines what type of service this is

Allowed values: "one time", "recurring", "expiring", "adjustment"

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Delete service

Delete a service. Be careful when using this method! Deletion will permanently disassociate the service from all accounts, packages and roles.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the service

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the service could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "That service does not exist.",
         "status_code": 404
     }
 }

Services - Get all services

https://example.sonar.software/api/v1/system/services

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups optional Array

An array of account group IDs

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null,
             "account_groups": []
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

https://example.sonar.software/api/v1/system/services

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null,
             "tax_exemption_amount": 25,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, adjustment or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service to exempt from taxation

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null,
             "tax_exemption_amount": 25
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, adjustment or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

HTTP/1.1 200 OK
{
     "data": [
         {
             "id": 1,
             "active": true,
             "name": "Bauch Group",
             "type": "expiring",
             "application": "debit",
             "amount": 53.74,
             "times_to_run": 5,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [
             1
             ],
             "roles": [],
             "data_service": false,
             "upload_in_kilobits": 0,
             "download_in_kilobits": 0,
             "technology_code": 0,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": null
         },
         {
             "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 40,
             "usage_based_billing_policy_id": null,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1
         },
     ],
     "paginator": {
         "total_count": 30,
         "total_pages": 15,
         "current_page": 1,
         "limit": 2
     }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, adjustment or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

HTTP/1.1 200 OK
{
    "data": [
    {
        "id": 1,
        "active": true,
        "name": "Bauch Group",
        "type": "expiring",
        "application": "debit",
        "amount": 53.74,
        "times_to_run": 5,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [
        1
        ],
        "roles": [],
        "data_service": false,
        "upload_in_kilobits": 0,
        "download_in_kilobits": 0,
        "technology_code": 0
    },
    {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40
    },
    ],
    "paginator": {
        "total_count": 30,
        "total_pages": 15,
        "current_page": 1,
        "limit": 2
    }
}

Services - Get all services

Get a list of the services in the system

https://example.sonar.software/api/v1/system/services

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, expiring, adjustment or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid on debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

HTTP/1.1 200 OK
{
  "data": [
        {
         "id": 1,
         "active": true,
         "name": "Gleichner-Rowe",
         "type": "expiring",
         "application": "debit",
         "amount": 21.30,
         "times_to_run": 6,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [
           1
         ],
         "roles": []
       },
       {
         "id": 2,
         "active": true,
         "name": "Balistreri Group",
         "type": "recurring",
         "application": "credit",
         "amount": 71.51,
         "times_to_run": 6,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [
           1
         ],
         "roles": []
       },
    ],
    "paginator": {
        "total_count": 30,
        "total_pages": 15,
        "current_page": 1,
        "limit": 2
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups optional Array

An array of account group IDs

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null,
             "account_groups": []
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
             "active": true,
             "name": "Schumm Ltd",
             "type": "recurring",
             "application": "debit",
             "amount": 63.62,
             "billing_frequency_in_months": 1,
             "times_to_run": 4,
             "limit_adjustments": false,
             "period_days": 0,
             "max_amount_per_period": "0.00",
             "taxes": [],
             "roles": [],
             "data_service": true,
             "upload_in_kilobits": 500,
             "download_in_kilobits": 1000,
             "technology_code": 70,
             "usage_based_billing_policy_id": 1,
             "unit_quantity_in_gigabytes": null,
             "general_ledger_code_id": 1,
             "tax_exemption_amount": 0,
             "voice_service": false,
             "unlimited_local_minutes": false,
             "unlimited_long_distance_minutes": false,
             "local_minutes": null,
             "local_minutes_amount": 0,
             "long_distance_minutes": null,
             "long_distance_minutes_amount": 0,
             "first_interval_in_seconds": null,
             "sub_interval_in_seconds": null,
             "local_prefixes": [],
             "inbound_toll_free_rate": null
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12,
        "tax_exemption_amount": 0,
        "voice_service": false,
        "unlimited_local_minutes": false,
        "unlimited_long_distance_minutes": false,
        "local_minutes": null,
        "local_minutes_amount": 0,
        "long_distance_minutes": null,
        "long_distance_minutes_amount": 0,
        "first_interval_in_seconds": null,
        "sub_interval_in_seconds": null,
        "local_prefixes": [],
        "inbound_toll_free_rate": null
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service to exempt from taxation

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12,
        "tax_exemption_amount": 0
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 12
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

 HTTP/1.1 200 OK
 {
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm Ltd",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 4,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 50
    }
}

Services - Get individual service

Get an individual service.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint, only valid for debit services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id optional Integer

The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups optional Array

An array of account group IDs

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

account_groups optional Array

An array of account group IDs

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null,
         "account_groups": [ 1 ]
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id optional Integer

The internal ID assigned to the service. You should omit this unless you explicitly need a specific ID to facilitate an import.

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second. Required if data_service is true.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second. Required if data_service is true.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true.

unit_quantity_in_gigabytes optional Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount. Required if type is overage.

general_ledger_code_id optional Integer

The ID of the general ledger code you wish to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

billing_frequency_in_months Integer

How often this service bills, 1 for monthly, 12 for annually, etc. Only valid for recurring services.

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
         "active": true,
         "name": "Schumm Ltd",
         "type": "recurring",
         "application": "debit",
         "amount": 63.62,
         "billing_frequency_in_months": 1,
         "times_to_run": 4,
         "limit_adjustments": false,
         "period_days": 0,
         "max_amount_per_period": "0.00",
         "taxes": [],
         "roles": [],
         "data_service": true,
         "upload_in_kilobits": 500,
         "download_in_kilobits": 1000,
         "technology_code": 70,
         "usage_based_billing_policy_id": 1,
         "unit_quantity_in_gigabytes": null,
         "general_ledger_code_id": 1,
         "tax_exemption_amount": 0,
         "voice_service": false,
         "unlimited_local_minutes": false,
         "unlimited_long_distance_minutes": false,
         "local_minutes": null,
         "local_minutes_amount": 0,
         "long_distance_minutes": null,
         "long_distance_minutes_amount": 0,
         "first_interval_in_seconds": null,
         "sub_interval_in_seconds": null,
         "local_prefixes": [],
         "inbound_toll_free_rate": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The internal ID of the service

active optional Boolean

Whether or not this service can still be added to accounts

name optional String

A descriptive name for the service

application optional String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount optional Number

The amount the service costs

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

general_ledger_code_id optional Integer

The ID of the general ledger code to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $50, but only $25 of it is taxable, set this to 25. Should be omitted in cases where the entirety of the service is taxable.

voice_service optional Boolean

Whether or not this is a voice service

unlimited_local_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes optional Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes optional Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount optional Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes optional Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount optional Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds optional Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds optional Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes optional Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate optional Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

voice_service Boolean

Whether or not this is a voice service

unlimited_local_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited local minutes

unlimited_long_distance_minutes Boolean

If this is a voice service, this describes whether the voice service offers unlimited long distance minutes

local_minutes Integer

If unlimited_local_minutes is false, this is the number of free local minutes provided with the service

local_minutes_amount Number

If unlimited_local_minutes is false, this is the cost per minute once the free minutes are used up.

long_distance_minutes Integer

If unlimited_long_distance_minutes is false, this is the number of free long distance minutes provided with the service

long_distance_minutes_amount Number

If unlimited_long_distance_minutes is false, this is the cost per minute once the free minutes are used up.

first_interval_in_seconds Integer

If this is a voice service, this is the minimum amount of time for each call. For example, if this is 60, then a 2 second call will always be charged at a 60 second rate.

sub_interval_in_seconds Integer

If this is a voice service, this is the minimum time per block after the first_interval_in_seconds. For example, if the first interval is 60, and the sub interval is 30, then a 61 second call will be charged at a 90 second rate.

local_prefixes Array

If this is a voice service, this is an array of local prefixes (e.g. area codes). Any calls that start with a prefix in this array will be classified as local.

inbound_toll_free_rate Number

If this is a voice service, this is the rate per minute charged for any inbound toll free calls

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1,
        "tax_exemption_amount": 0,
        "voice_service": false,
        "unlimited_local_minutes": false,
        "unlimited_long_distance_minutes": false,
        "local_minutes": null,
        "local_minutes_amount": 0,
        "long_distance_minutes": null,
        "long_distance_minutes_amount": 0,
        "first_interval_in_seconds": null,
        "sub_interval_in_seconds": null,
        "local_prefixes": [],
        "inbound_toll_free_rate": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The internal ID of the service

active optional Boolean

Whether or not this service can still be added to accounts

name optional String

A descriptive name for the service

application optional String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount optional Number

The amount the service costs

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

general_ledger_code_id optional Integer

The ID of the general ledger code to assign to this service

tax_exemption_amount optional Number

The amount of the service to exempt from taxation. For example, if this service costs $60, but only $35 of it is taxable, set this to 25 (60-35 = 25). Should be omitted or set to 0 in cases where the entirety of the service is taxable.

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

tax_exemption_amount Number

The amount of the service cost to exempt from taxation

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1,
        "tax_exemption_amount": 0
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The internal ID of the service

active optional Boolean

Whether or not this service can still be added to accounts

name optional String

A descriptive name for the service

application optional String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount optional Number

The amount the service costs

times_to_run optional Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments optional Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days optional Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period optional Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes optional Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles optional Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service optional Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits optional Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits optional Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code optional Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id optional Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

general_ledger_code_id optional Integer

The ID of the general ledger code to assign to this service

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring, overage, or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint.

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

usage_based_billing_policy_id Integer

The ID of the usage based billing policy applied to this service. Only valid if data_service is true

unit_quantity_in_gigabytes Integer

If this is an overage service, this is the amount of gigabytes provided for the cost specified in amount

general_ledger_code_id Integer

The ID of the general ledger code assigned to this service

HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40,
        "usage_based_billing_policy_id": 1,
        "unit_quantity_in_gigabytes": null,
        "general_ledger_code_id": 1
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
{
    "error": {
        "message": {
        "type": "magic is not a valid service type"
    },
        "status_code": 422
    }
}

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

data_service Boolean

Only valid for recurring services. If this is true, this is a data service (e.g. it provides data/Internet connectivity to an end user.)

download_in_kilobits Integer

Only valid if data_service is true. The download speed of the service in kilobits per second.

upload_in_kilobits Integer

Only valid if data_service is true. The upload speed of the service in kilobits per second.

technology_code Integer

The technology code for the service. Only required if this is a data service. This is mostly used for generating the FCC Form 477 report, and the integers correspond to the following types. 0 = Other, 10 = Asymmetric xDSL, 20 = Symmetric xDSL, 30 = Copper Wireline, 40 = Cable Modem, 50 = Fiber, 60 = Satellite, 70 = Terrestrial Fixed Wireless, 90 = Electric Power Line.

Default value: 0

Allowed values: "0", "10", "20", "30", "40", "50", "60", "70", "90"

 HTTP/1.1 200 OK
{
    "data": {
        "id": 3,
        "active": true,
        "name": "Schumm's Super Internet",
        "type": "recurring",
        "application": "debit",
        "amount": 63.62,
        "times_to_run": 1,
        "limit_adjustments": false,
        "period_days": 0,
        "max_amount_per_period": "0.00",
        "taxes": [],
        "roles": [],
        "data_service": true,
        "upload_in_kilobits": 500,
        "download_in_kilobits": 1000,
        "technology_code": 40
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
         {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

Services - Update service

Update a service. The type cannot be changed.

https://example.sonar.software/api/v1/system/services/:id

Parameter

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

application String

One of credit or debit, defines whether or not the service applies or charge or a discount

Allowed values: "credit", "debit"

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

Success 200

Field Type Description
id Number

The internal ID of the service

active Boolean

Whether or not this service can still be added to accounts

name String

A descriptive name for the service

type String

One of one time, adjustment, expiring or recurring

application String

One of credit or debit

amount Number

The amount the service costs

times_to_run Number

This is only used for expiring services, it represents the number of times the service will run before being expired from the account. Setting this value on any other service does nothing

limit_adjustments Boolean

This is only used for adjustment services. If it is true, then the period_days and max_amount_per_period values are applied. If false, they are ignored

Default value: false

period_days Number

This is only used for adjustment services, it represents the number of days tracked for the max_amount_per_period value

max_amount_per_period Number

This is only used for adjustment services. If it is greater than 0, a user can only apply this adjustment service until they have applied up to max_period_per_days amount, within a rolling window defined by period_days

taxes Array

An array of tax IDs that are assessed on this service. Get details from the /taxes endpoint. This is only valid on 'debit' services

roles Array

An array of role IDs. This is only valid for adjustment based services - it controls which roles can apply this adjustment

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "active": true,
    "name": "Gleichner-Rowe",
    "type": "expiring",
    "application": "debit",
    "amount": 21.30,
    "times_to_run": 6,
    "limit_adjustments": false,
    "period_days": 0,
    "max_amount_per_period": "0.00",
    "taxes": [
      1
    ],
    "roles": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "magic is not a valid service type"
         },
         "status_code": 422
     }
 }

System

System - Create account group

Create a new account group.

https://example.sonar.software/api/v1/system/account_groups

Parameter

Field Type Description
name String

A unique name for the account group

Success 200

Field Type Description
id Number

The ID of the account group, this can be used when setting an account group on an account

name String

A descriptive name of the account group

HTTP/1.1 201 OK
{
    "data": {
        "id": 6,
        "name": "People That I Like"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account status

Create a new account status.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field Type Description
name String

A unique name for the account status

active Boolean

Whether or not the status should activate customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

HTTP/1.1 201 OK
{
    "data": {
         "id": 5,
         "name": "Sent to Collections",
         "active": false,
         "color": "#00ffff",
         "account_super_user_only": true
     }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account status

Create a new account status.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field Type Description
name String

A unique name for the account status

active Boolean

Whether or not the status should activate customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

HTTP/1.1 201 OK
{
    "data": {
         "id": 5,
         "name": "Sent to Collections",
         "active": false,
         "color": "#00ffff"
     }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create account type

Create a new account type.

https://example.sonar.software/api/v1/system/account_types

Parameter

Field Type Description
name String

A unique name for the account type

type String

The type of account type this is

Allowed values: "residential", "commercial"

Success 200

Field Type Description
id Number

The ID of the account type, this can be used when setting the account type on an account

name String

A descriptive name of the account type

type String

The type of status this is

Allowed values: "residential", "commercial"

HTTP/1.1 201 OK
{
    "data": {
         "id": 12,
         "name": "My Custom Type",
         "type": "commercial"
     }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create address type

Create a new address type.

https://example.sonar.software/api/v1/system/address_types

Parameter

Field Type Description
name String

A unique name for the address type

Success 200

Field Type Description
id Number

The ID of the address type, this can be used when setting the address type on an address

name String

A descriptive name of the address type

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Create custom field

Create a new custom field.

https://example.sonar.software/api/v1/system/custom_fields

Parameter

Field Type Description
name String

The name of the custom field

type String

The type of field

Allowed values: "text", "checkbox", "select", "date"

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields and should not be submitted for other types

active Boolean

If the field is not active, it won't show up on any entities that don't already have a value set

entity_type String

The type of entity this custom field is displayed on

Allowed values: "account"

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details. This field should not be submitted for other types

Success 200

Field Type Description
id Number

The internal id of the custom field

name String

The name of the custom field

type String

The type of field

Allowed values: "text", "checkbox", "select", "date"

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields

active Boolean

If the field is not active, it won't show up on any entities that don't already have a value set

entity_type String

The type of entity this custom field is displayed on

Allowed values: "account"

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

HTTP/1.1 201 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "type": "The value entered for type is invalid."
         },
         "status_code": 422
     }
 }

System - Delete account group

Delete an account group.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field Type Description
id Number

The ID of the account group

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account group deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account group could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Account group not found",
         "status_code": 404
     }
 }

System - Delete account status

Delete an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "Account status deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account status could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Account status not found",
         "status_code": 404
     }
 }

System - Delete account type

Delete an account types.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field Type Description
id Number

The ID of the account type

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

A

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account type could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Account type not found",
         "status_code": 404
     }
 }

System - Delete address type

Delete an account type.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field Type Description
id Number

The ID of the address type

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the account status could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Address type not found",
         "status_code": 404
     }
 }

System - Delete custom field

Delete a custom field. This will remove all data stored in this custom field from all entities also. If you just want to disable further use of the field, set the 'active' property to 'false'.

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field Type Description
id Number

The ID of the custom field

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the custom field could not be deleted

status_code Number

4xx

HTTP/1.1 404
 {
     "error": {
         "message": "Custom field does not exist.",
         "status_code": 404
     }
 }

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field Type Description
active_accounts Integer

The number of active accounts in the system.

delinquent_accounts Integer

The number of delinquent accounts

all_accounts Integer

A total count of accounts

invoiced_this_month Float

The amount invoiced this month

total_due_balances Float

A total of all due balances

undeposited_payments Integer

A count of undeposited payments

invoices_to_print Integer

The total count of invoices pending printing

open_public_tickets Integer

The total open public tickets

open_internal_tickets Integer

The total open internal tickets

tickets_by_group Object

An object where the property is a ticket group ID and the value is the number of tickets open in that group

ticket_group_names Object

A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display

count_of_accounts_status_changed_in_last_30_days Integer

A count of accounts that have changed status in some way in the last 30 days

today Object

An object, described directly below this entry, that contains various statistics that are only true for today

tickets Integer

Tickets opened today

tickets_closed Integer

Tickets closed today

payments Float

The amount of all payments made today

payments_failed Integer

A count of failed payments today

accounts Integer

Accounts created today

debits Float

The amount of all debits created today

discounts Float

The amount of all discounts created today

customers_billed Integer

A count of all customers billed today

accounts_activated Integer

Accounts activated today

bounced_emails Integer

A count of bounced emails today

contracts_expiring Integer

A count of contracts expiring within 90 days

towercoverage_submissions_good Integer

A count of accepted submissions from TowerCoverage.com today

towercoverage_submissions_bad Integer

A count of rejected submissions from TowerCoverage.com today

jobs Object

An object providing some information on jobs today, described below

scheduled Integer

A count of jobs scheduled today

completed Integer

A count of jobs completed today

failed Integer

A count of jobs failed today

accounts_by_status_id Object

An object where the property is the account status ID, and the value is the count of customers with that status ID.

arpu Float

The average revenue per user

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        },
        "accounts_by_status_id": {
           "2": 1234,
           "5": 5678
           "12": 2
        },
        "arpu": 12.34
    }
}

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field Type Description
active_accounts Integer

The number of active accounts in the system.

delinquent_accounts Integer

The number of delinquent accounts

all_accounts Integer

A total count of accounts

invoiced_this_month Float

The amount invoiced this month

total_due_balances Float

A total of all due balances

undeposited_payments Integer

A count of undeposited payments

invoices_to_print Integer

The total count of invoices pending printing

open_public_tickets Integer

The total open public tickets

open_internal_tickets Integer

The total open internal tickets

tickets_by_group Object

An object where the property is a ticket group ID and the value is the number of tickets open in that group

ticket_group_names Object

A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display

count_of_accounts_status_changed_in_last_30_days Integer

A count of accounts that have changed status in some way in the last 30 days

today Object

An object, described directly below this entry, that contains various statistics that are only true for today

tickets Integer

Tickets opened today

tickets_closed Integer

Tickets closed today

payments Float

The amount of all payments made today

payments_failed Integer

A count of failed payments today

accounts Integer

Accounts created today

debits Float

The amount of all debits created today

discounts Float

The amount of all discounts created today

customers_billed Integer

A count of all customers billed today

accounts_activated Integer

Accounts activated today

bounced_emails Integer

A count of bounced emails today

contracts_expiring Integer

A count of contracts expiring within 90 days

towercoverage_submissions_good Integer

A count of accepted submissions from TowerCoverage.com today

towercoverage_submissions_bad Integer

A count of rejected submissions from TowerCoverage.com today

jobs Object

An object providing some information on jobs today, described below

scheduled Integer

A count of jobs scheduled today

completed Integer

A count of jobs completed today

failed Integer

A count of jobs failed today

accounts_by_status_id Object

An object where the property is the account status ID, and the value is the count of customers with that status ID.

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        },
        "accounts_by_status_id": {
           "2": 1234,
           "5": 5678
           "12": 2
        }
    }
}

System - Get KPIs and statistics

Get various key performance indicators and statistics. This data is collected in real time, so should be queried daily and stored if you want to track it over time.

https://example.sonar.software/api/v1/_data/kpi

Success 200

Field Type Description
active_accounts Integer

The number of active accounts in the system.

delinquent_accounts Integer

The number of delinquent accounts

all_accounts Integer

A total count of accounts

invoiced_this_month Float

The amount invoiced this month

total_due_balances Float

A total of all due balances

undeposited_payments Integer

A count of undeposited payments

invoices_to_print Integer

The total count of invoices pending printing

open_public_tickets Integer

The total open public tickets

open_internal_tickets Integer

The total open internal tickets

tickets_by_group Object

An object where the property is a ticket group ID and the value is the number of tickets open in that group

ticket_group_names Object

A helper object that corresponds ticket group names to the IDs in tickets_by_group for easier display

count_of_accounts_status_changed_in_last_30_days Integer

A count of accounts that have changed status in some way in the last 30 days

today Object

An object, described directly below this entry, that contains various statistics that are only true for today

tickets Integer

Tickets opened today

tickets_closed Integer

Tickets closed today

payments Float

The amount of all payments made today

payments_failed Integer

A count of failed payments today

accounts Integer

Accounts created today

debits Float

The amount of all debits created today

discounts Float

The amount of all discounts created today

customers_billed Integer

A count of all customers billed today

accounts_activated Integer

Accounts activated today

bounced_emails Integer

A count of bounced emails today

contracts_expiring Integer

A count of contracts expiring within 90 days

towercoverage_submissions_good Integer

A count of accepted submissions from TowerCoverage.com today

towercoverage_submissions_bad Integer

A count of rejected submissions from TowerCoverage.com today

jobs Object

An object providing some information on jobs today, described below

scheduled Integer

A count of jobs scheduled today

completed Integer

A count of jobs completed today

failed Integer

A count of jobs failed today

HTTP/1.1 200 OK
{
    "data": {
        "active_accounts": 1,
        "delinquent_accounts": 0,
        "all_accounts": 1,
        "invoiced_this_month": null,
        "total_due_balances": null,
        "undeposited_payments": 0,
        "invoices_to_print": 0,
        "open_public_tickets": 0,
        "open_internal_tickets": 0,
        "tickets_by_group": [],
        "ticket_group_names": [],
        "count_of_accounts_status_changed_in_last_30_days": 0,
        "today": {
            "tickets": 0,
            "tickets_closed": 0,
            "payments": "150.00",
            "payments_failed": 2,
            "accounts": 0,
            "debits": null,
            "discounts": null,
            "customers_billed": 0,
            "jobs": {
                "scheduled": 0,
                "completed": 0,
                "failed": 0
            },
            "accounts_activated": 0,
            "bounced_emails": 0,
            "contracts_expiring": 0,
            "towercoverage_submissions_good": 0,
            "towercoverage_submissions_bad": 0
        }
    }
}

System - Get all account groups

Get a list of available account groups.

https://example.sonar.software/api/v1/system/account_groups

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the account group, this can be used when setting an account group on an account

name String

A descriptive name of the account group

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Habitual Late Payers"
        },
        {
            "id": 2,
            "name": "JC Kenney Employees"
        },
        {
            "id": 3,
            "name": "Free Accounts"
        },
        {
            "id": 4,
            "name": "Employees"
        },
        {
            "id": 5,
            "name": "Friends & Family"
        }
    ],
    "paginator": {
        "total_count": 5,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account statuses

Get a list of available account statuses.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Lead",
            "active": false,
            "color": "#9b59b6",
            "account_super_user_only": false
        },
        {
            "id": 2,
            "name": "Active",
            "active": true,
            "color": "#123123",
            "account_super_user_only": false
        },
        {
            "id": 3,
            "name": "Inactive",
            "active": false,
            "color": "#fff000",
            "account_super_user_only": false
        },
        {
            "id": 5,
            "name": "My Custom Status Active",
            "active": true
            "color": "#00ff00",
            "account_super_user_only": true
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account statuses

Get a list of available account statuses.

https://example.sonar.software/api/v1/system/account_statuses

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Lead",
            "active": false,
            "color": "#9b59b6"
        },
        {
            "id": 2,
            "name": "Active",
            "active": true,
            "color": "#123123"
        },
        {
            "id": 3,
            "name": "Inactive",
            "active": false,
            "color": "#fff000"
        },
        {
            "id": 5,
            "name": "My Custom Status Active",
            "active": true
            "color": "#00ff00"
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all account types

Get a list of available account types.

https://example.sonar.software/api/v1/system/account_types

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the account type, this can be used when setting the account type on an account

name String

A descriptive name of the account type

type String

The type of account type this is

Allowed values: "residential", "commercial"

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 1,
            "name": "Residential",
            "type": "residential",
        },
        {
            "id": 2,
            "name": "Commercial",
            "type": "commercial",
        },
        {
            "id": 3,
            "name": "Service Trade",
            "type": "commercial",
        }
   ],
   "paginator": {
       "total_count": 6,
       "total_pages": 1,
       "current_page": 1,
       "limit": 100
   }
}

System - Get all address types

Get a list of available address types.

https://example.sonar.software/api/v1/system/address_types

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the address type, this can be used when setting the address type on an address

name String

A descriptive name of the address type

 HTTP/1.1 200 OK
 {
    "data": [
        {
            "id": 1,
            "name": "Physical"
        },
        {
            "id": 2,
            "name": "Billing"
        },
        {
            "id": 3,
            "name": "Billing"
        },
        {
            "id": 4,
            "name": "Some Other Type"
        }
    ],
    "paginator": {
        "total_count": 4,
        "total_pages": 1,
        "current_page": 1,
        "limit": 100
    }
}

System - Get all custom fields

Get a list of custom fields

https://example.sonar.software/api/v1/system/custom_fields

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the custom field

name String

The name of the custom field

type String

The type of field

Allowed values: "text", "checkbox", "select", "date"

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields

active Boolean

If the field is not active, it won't show up on any entities that don't already have a value set

entity_type String

The type of entity this custom field is displayed on

Allowed values: "account"

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 8,
      "name": "Serial Number for Anti-Virus",
      "type": "text",
      "unique": true,
      "active": true,
      "entity_type": "account",
      "select_options": []
    },
    {
      "id": 7,
      "name": "My First Dropdown",
      "type": "select",
      "unique": false,
      "active": false,
      "entity_type": "account",
      "select_options": [
        {
          "text": "Option Number One"
        },
        {
          "text": "Option Number Two"
        }
      ]
    },
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

System - Get application configuration

Get the current application configuration.

https://example.sonar.software/api/v1/system/application

Success 200

Field Type Description
locale String

The application locale

timezone String

The application timezone

country String

An ISO 3166-1 alpha-2 character code representing the country the application is configured for

thousands_separator String

The character to use to separate thousands (e.g. 1,000 has a comma (,) separator)

decimal_separator String

The character to use to separate decimals (e.g. 100.34 has a period (.) separator)

date_format String

The format for dates in the application

currency_symbol String

The symbol used for currency in the application

time_format String

The format used for time in the application

units String

The units used for measurement (metric or imperial)

HTTP/1.1 200 OK
{
"data": {
"locale": "en",
"timezone": "America/Chicago",
"country": "US",
"thousands_separator": ",",
"decimal_separator": ".",
"date_format": "m/d/Y",
"currency_symbol": "$",
"time_format": "g:i:s",
"units": "metric"
}
}

System - Get individual account group

Get an individual account status.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The ID of the account group, this can be used when setting an account group on an account

name String

A descriptive name of the account group

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Habitual Late Payers"
    }
}

System - Get individual account status

Get an individual account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Lead",
        "active": false,
        "color": "#00ff00",
        "account_super_user_only": false
    }
}

System - Get individual account status

Get an individual account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field Type Description
id Number

The ID of the account status

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Lead",
        "active": false,
        "color": "#00ff00"
    }
}

System - Get individual account type

Get an individual account type.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field Type Description
id Number

The ID of the account type

Success 200

Field Type Description
id Number

The ID of the account type, this can be used when setting the account type on an account

name String

A descriptive name of the account type

type String

The type of account type this is

Allowed values: "residential", "commercial"

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Residential",
        "type": "residential"
    }
}

System - Get individual address type

Get an individual account address.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field Type Description
id Number

The ID of the address type

Success 200

Field Type Description
id Number

The ID of the address type, this can be used when setting the address type on an address

name String

A descriptive name of the address type

HTTP/1.1 200 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

System - Get individual custom field

Get an individual custom field

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field Type Description
id Number

The id of the custom field

Success 200

Field Type Description
id Number

The internal id of the custom field

name String

The name of the custom field

type String

The type of field

Allowed values: "text", "checkbox", "select", "date"

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields

active Boolean

If the field is not active, it won't show up on any entities that don't already have a value set

entity_type String

The type of entity this custom field is displayed on

Allowed values: "account"

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

HTTP/1.1 200 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

System - Update account group

Update an account group.

https://example.sonar.software/api/v1/system/account_groups/:id

Parameter

Field Type Description
id Number

The ID of the account group to update

name String

A unique name for the account group

Success 200

Field Type Description
id Number

The ID of the account group, this can be used when setting an account group on an account

name String

A descriptive name of the account group

 HTTP/1.1 200 OK
 {
    "data": {
        "id": 6,
        "name": "People That I No Longer Like"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account status

Update an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field Type Description
id Number

The ID of the account status to update

name String

A unique name for the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

account_super_user_only Boolean

If this is true, only users in a role with the 'Account Super User' permission can set this status on an account

HTTP/1.1 200 OK
{
    "data": {
       "id": 5,
       "name": "Pending",
       "active": false,
       "color": "#00ff00",
       "account_super_user_only": true
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account status

Update an account status.

https://example.sonar.software/api/v1/system/account_statuses/:id

Parameter

Field Type Description
id Number

The ID of the account status to update

name String

A unique name for the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

Success 200

Field Type Description
id Number

The ID of the account status, this can be used when setting the account status on an account

name String

A descriptive name of the account status

active Boolean

Whether or not this status activates customer services

color String

A 6 digit hex code, prefixed with #, that represents the color for the status in the application

HTTP/1.1 200 OK
{
    "data": {
       "id": 5,
       "name": "Pending",
       "active": false,
       "color": "#00ff00"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update account type

Update an account type.

https://example.sonar.software/api/v1/system/account_types/:id

Parameter

Field Type Description
id Number

The ID of the account type to update

name String

A unique name for the account type

type String

The type of account type this is

Allowed values: "residential", "commercial"

Success 200

Field Type Description
id Number

The ID of the account type, this can be used when setting the account type on an account

name String

A descriptive name of the account type

type String

The type of status this is

Allowed values: "residential", "commercial"

HTTP/1.1 200 OK
{
    "data": {
         "id": 12,
         "name": "My Custom Type Updated",
         "type": "commercial"
     }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update address type

Update an address type.

https://example.sonar.software/api/v1/system/address_types/:id

Parameter

Field Type Description
id Number

The ID of the address type to update

name String

A unique name for the address type

Success 200

Field Type Description
id Number

The ID of the address type, this can be used when setting the address type on an address

name String

A descriptive name of the address type

HTTP/1.1 201 OK
{
    "data": {
        "id": 1,
        "name": "Physical"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "name": "The name has already been taken.",
         },
         "status_code": 422
     }
 }

System - Update application

Update application

https://example.sonar.software/api/v1/system/application

Parameter

Field Type Description
locale optional String

The application locale. You can retrieve a list of valid locales from /_data/locales

timezone optional String

The application timezone. You can retrieve a list of valid timezones from /_data/timezones

country optional String

An ISO 3166-1 alpha-2 character code representing the country the application is configured for. You can retrieve a list of these from /_data/countries

thousands_separator optional String

The character to use to separate thousands (e.g. 1,000 has a comma (,) separator). Typical options are a space, a comma or a period, although the application allows any characters.

decimal_separator optional String

The character to use to separate decimals (e.g. 100.34 has a period (.) separator). Typical options are a comma or a period, although the application allows any characters.

date_format optional String

The format for dates in the application. One of Y-m-d, d/m/Y or m/d/Y. These will format to 2015-01-30, 30/01/2015 and 01/30/2015 respectively.

currency_symbol optional String

The symbol used for currency in the application. Any characters are allowed.

time_format optional String

The format used for time in the application, one of g:i:s and H:i:s. These will format to 1:30:34 PM and 13:30:34 respectively.

Allowed values: "g:i:s", "H:i:s"

units optional String

The units used for measurement

Allowed values: "metric", "imperial"

Success 200

Field Type Description
locale String

The application locale

timezone String

The application timezone

thousands_separator String

The character to use to separate thousands (e.g. 1,000 has a comma (,) separator)

decimal_separator String

The character to use to separate decimals (e.g. 100.34 has a period (.) separator)

date_format String

The format for dates in the application

currency_symbol String

The symbol used for currency in the application

time_format String

The format used for time in the application

units String

The units used for measurement (metric or imperial)

HTTP/1.1 200 OK
{
    "data": {
       "locale": "en",
        "timezone": "America/Chicago",
        "country": "US",
        "thousands_separator": ",",
        "decimal_separator": ".",
        "date_format": "m/d/Y",
        "currency_symbol": "$",
        "time_format": "g:i:s",
        "units": "metric"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
            "message": {
            "locale": "The selected language is invalid."
         },
         "status_code": 422
     }
 }

System - Update custom field

Update a custom field. The type and entity_type cannot be changed once created

https://example.sonar.software/api/v1/system/custom_fields/:id

Parameter

Field Type Description
id Number

The ID of the custom field

name String

The name of the custom field

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields and should not be submitted for other types

active Boolean

If the field is not active, it won't show up on any entities that don't already have a value set

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details. This field should not be submitted for other types

Success 200

Field Type Description
id Number

The internal id of the custom field

name String

The name of the custom field

type String

The type of field

Allowed values: "text", "checkbox", "select"

unique Boolean

Whether input to this custom field must be unique. Only applies to text fields

active Boolean

If the field is not active, it won't show up on any accounts that don't already have a value set

entity_type String

The type of entity this custom field is displayed on

Allowed values: "account"

select_options Array

If the type of this field is 'select', this will contain an array of options to display in the select field, formatted as JSON - see example for details

HTTP/1.1 200 OK
{
  "id": 8,
  "name": "Height of Antenna",
  "type": "text",
  "unique": true,
  "active": true,
  "entity_type": "account",
  "select_options": []
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "unique": "Unique must be a boolean."
         },
         "status_code": 422
     }
 }

Task Templates

Task_Templates - Create a new task template

Create a new task template.

https://example.sonar.software/api/v1/system/misc/task_templates

Parameter

Field Type Description
name String

A name for the task template

Success 200

Field Type Description
id Number

The ID of the task template.

name String

The name of the task template

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Task_Templates - Create a new template task.

Create a new template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks

Parameter

Field Type Description
name String

A name for the template task

Success 200

Field Type Description
id Number

The ID of the task template.

task String

The name of the task

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "task": "Wash the dishes",
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Task_Templates - Delete a task template

Delete a task template

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field Type Description
id Number

The ID of the task template

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the task template could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "task template does not exist.",
         "status_code": 404
     }
 }

Task_Templates - Delete a template task.

Delete a template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:template_task_id

Parameter

Field Type Description
id Number

The ID of the task template

template_task_id Number

The ID of the template task

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the template task could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "template task does not exist.",
         "status_code": 404
     }
 }

Task_Templates - Get all task templates

Get all task templates

https://example.sonar.software/api/v1/system/misc/task_templates

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the task template.

name String

The name of the task template

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Installation tasks"
    },
    {
      "id": 1,
      "name": "Service call tasks"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Task_Templates - Get all template tasks.

Get all template tasks. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the task template.

task String

The name of the task

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 7,
      "task": "Do something"
    },
    {
      "id": 6,
      "task": "test"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Task_Templates - Get an individual task template

Get an individual task template

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field Type Description
id Number

The ID of the task template

Success 200

Field Type Description
id Number

The ID of the task template.

name String

The name of the task template

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Some random tasks"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Get an individual template task.

Get an individual template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:template_task_id

Parameter

Field Type Description
id Number

The ID of the task template

template_task_id Number

The ID of the template task

Success 200

Field Type Description
id Number

The ID of the template task.

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "task": "Do something"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Update task template

Update an existing task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id

Parameter

Field Type Description
id Number

The task template ID

name optional String

The name of the task template

Success 200

Field Type Description
id Number

The ID of the task template.

name String

The name of the task template

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "A bunch of tasks"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Task_Templates - Update template task.

Update an existing template task. A template task is a task contained within a task template.

https://example.sonar.software/api/v1/system/misc/task_templates/:id/template_tasks/:task_template_id

Parameter

Field Type Description
id Number

The task template ID

template_task_id Number

The template task ID

Success 200

Field Type Description
id Number

The ID of the template task.

task String

The task

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "task": "Jump rope"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tasks

Tasks - Attach a task to an entity

Attach a task to an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity to attach to.

Allowed values: "tickets", "accounts", "network_sites", "jobs"

description String

A description of the task

user_id optional Number

The ID of a user you want to assign this task to

due_date optional Date

The date the task is due

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "description": "Build a space elevator.",
    "user_id": 2,
    "due_date": "2016-01-02",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Attach a task to an entity

Attach a task to an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity to attach to.

Allowed values: "tickets", "accounts", "network_sites"

description String

A description of the task

user_id optional Number

The ID of a user you want to assign this task to

due_date optional Date

The date the task is due

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "description": "Build a space elevator.",
    "user_id": 2,
    "due_date": "2016-01-02",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Delete a task

Delete a task from an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

task_id Number

The ID of the task

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the task could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Task does not exist.",
         "status_code": 404
     }
 }

Tasks - Delete a task

Delete a task from an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites"

task_id Number

The ID of the task

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the task could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Task does not exist.",
         "status_code": 404
     }
 }

Tasks - Get all tasks on an entity

Get all tasks on an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "description": "Here's a description of what I want you to do.",
      "user_id": 1,
      "due_date": "2016-05-03",
      "complete": false,
      "completed_by": null,
      "completed_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tasks - Get all tasks on an entity

Get all tasks on an entity.

https://example.sonar.software/api/v1/:entity/:id/tasks

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets"

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 5,
      "description": "Here's a description of what I want you to do.",
      "user_id": 1,
      "due_date": "2016-05-03",
      "complete": false,
      "completed_by": null,
      "completed_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tasks - Get an individual task

Get an individual task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

task_id Number

The ID of the task

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Tasks - Get an individual task

Get an individual task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets"

task_id Number

The ID of the task

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

 HTTP/1.1 200 OK
 {
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": false,
    "completed_by": null,
    "completed_at": null
  }
}

Tasks - Update a task

Update an existing task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites", "jobs"

task_id Number

The ID of the task

description optional String

A description of the task

user_id optional Number

The ID of a user you want to assign this task to

due_date optional Date

The date the task is due

complete optional Boolean

Set to true if the task is complete, or false if not.

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": true,
    "completed_by": 1,
    "completed_at": "2016-05-02 23:59:59"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Tasks - Update a task

Update an existing task.

https://example.sonar.software/api/v1/:entity/:id/tasks/:task_id

Parameter

Field Type Description
id Number

The ID of the entity

entity String

The entity

Allowed values: "tickets", "accounts", "network_sites"

task_id Number

The ID of the task

description optional String

A description of the task

user_id optional Number

The ID of a user you want to assign this task to

due_date optional Date

The date the task is due

complete optional Boolean

Set to true if the task is complete, or false if not.

Success 200

Field Type Description
id Number

The ID of the task

description String

The description of the task

user_id Number

The ID of the user assigned to the task

due_date Date

The date the task is due

complete Boolean

Whether or not the task has been completed

completed_by String

The user ID of the person who completed the task, if it has been completed

completed_at DateTime

The date and time in UTC that the task was completed, if it has been completed

HTTP/1.1 200 OK
{
  "data": {
    "id": 7,
    "description": "Here's a description of what I want you to do.",
    
    "user_id": 1,
    "due_date": "2016-05-03",
    "complete": true,
    "completed_by": 1,
    "completed_at": "2016-05-02 23:59:59"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "id": "The ID must be an integer."
     },
     "status_code": 422
   }
 }

Ticket Categories

Ticket_Categories - Create a new ticket category

Create a new ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories

Parameter

Field Type Description
name String

A name for the ticket category

Success 200

Field Type Description
id Number

The ID of the ticket category.

name String

The name of the ticket category.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name is already in use."
     },
     "status_code": 422
   }
 }

Ticket_Categories - Delete ticket category

Delete a ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field Type Description
id Number

The ID of the ticket category

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the ticket category could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket category does not exist.",
         "status_code": 404
     }
 }

Ticket_Categories - Get all ticket categories

Get all ticket categories

https://example.sonar.software/api/v1/system/tickets/ticket_categories

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the ticket category.

name String

The name of the ticket category.

HTTP/1.1 200 OK
{
  "data": [
    {
    "id": 2,
    "name": "The porridge was too hot"
   },
   {
    "id": 3,
    "name": "The porridge was too cold"
   }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Ticket_Categories - Get an individual ticket category

Get an individual ticket category

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field Type Description
id Number

The ID of the ticket category

Success 200

Field Type Description
id Number

The ID of the ticket category.

name String

The name of the ticket category.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket_Categories - Update ticket category

Update an existing ticket category.

https://example.sonar.software/api/v1/system/tickets/ticket_categories/:id

Parameter

Field Type Description
id Number

The ID of the ticket category.

name optional String

The name of the ticket category.

Success 200

Field Type Description
id Number

The ID of the ticket category.

name String

The name of the ticket category.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "The porridge was too hot"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket Groups

Ticket_Groups - Create a new ticket group

Create a new ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups

Parameter

Field Type Description
name String

A name for the ticket group

private optional Boolean

Whether the group is private

Default value: false

enabled optional Boolean

Whether the group is enabled

Default value: true

users optional Array

An array of user IDs that are associated with the group

Success 200

Field Type Description
id Number

The ID of the ticket group.

name String

The name of the ticket group

private Boolean

Whether the group is private

enabled Boolean

Whether the group is enabled

users Array

An array of user IDs that are associated with the group

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Some test name",
    "private": false,
    "enabled": true,
    "users": [
       1,
       2
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name is already taken."
     },
     "status_code": 422
   }
 }

Ticket_Groups - Delete ticket group

Delete a ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field Type Description
id Number

The ID of the ticket group

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the ticket group could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket group does not exist.",
         "status_code": 404
     }
 }

Ticket_Groups - Get all ticket groups

Get all tickets

https://example.sonar.software/api/v1/system/tickets/ticket_groups

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the ticket group.

name String

The name of the ticket group

private Boolean

Whether the group is private

enabled Boolean

Whether the group is enabled

users Array

An array of user IDs that are associated with the group

HTTP/1.1 200 OK
{
  "data": [
    {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   },
   {
     "id": 4,
     "name": "Test yet again",
     "private": false,
     "enabled": true,
     "users": [
       1
     ]
   }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Ticket_Groups - Get an individual ticket group

Get an individual ticket group

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field Type Description
id Number

The ID of the ticket group

Success 200

Field Type Description
id Number

The ID of the ticket group.

name String

The name of the ticket group

private Boolean

Whether the group is private

enabled Boolean

Whether the group is enabled

users Array

An array of user IDs that are associated with the group

HTTP/1.1 200 OK
{
  "data": {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Ticket_Groups - Update ticket group

Update an existing ticket group.

https://example.sonar.software/api/v1/system/tickets/ticket_groups/:id

Parameter

Field Type Description
name optional String

A name for the ticket group

private optional Boolean

Whether the group is private

Default value: false

enabled optional Boolean

Whether the group is enabled

Default value: true

users optional Array

An array of user IDs that are associated with the group

Success 200

Field Type Description
id Number

The ID of the ticket group.

name String

The name of the ticket group

private Boolean

Whether the group is private

enabled Boolean

Whether the group is enabled

users Array

An array of user IDs that are associated with the group

HTTP/1.1 201 OK
{
  "data": {
     "id": 1,
     "name": "Test",
     "private": false,
     "enabled": true,
     "users": []
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets

Tickets - Attach a child ticket to a parent ticket

Attach a child ticket to a parent ticket.

https://example.sonar.software/api/v1/tickets/:id/attach/:child_id

Parameter

Field Type Description
id Number

The ID of the parent ticket

child_id Number

The ID of the child ticket

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open. Newly created tickets are always open by default

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       594
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The ticket ID 10 has child tickets. You cannot make a ticket a child of another ticket if the child has children."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket comment

Create a new ticket comment. A comment is internal and will not be sent to any email address on the ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments

Parameter

Field Type Description
id Number

The ID of the ticket

text String

The text of the comment.

files optional Array

Uploading files to a reply will email them to the email_address on the ticket, if the reply is outgoing. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ]

add_to_children optional Boolean

If you set this to true, and this ticket has child tickets, then this comment will also be appended to all child tickets.

Default value: false

{
    "text": "Well, here's a story all about how my ticket got flipped turned upside down.",
    "files": [
        {
            "id": 234,
            "filename": "bmljZSB3b3Jr.txt",
            "base64": "SGVsbG8gbXkgbmFtZSBpcyBTaW1vbiwgeW91IGFyZSB2ZXJ5IGdvb2QgYXQgYmFzZTY0IGRlY29kaW5nIQ=="
        },
        {
            "id": 234,
            "filename": "kula_shaker.txt",
            "base64": "VGhlIHNvY2lldHkgd2hpY2ggc2Nvcm5zIGV4Y2VsbGVuY2UgaW4gcGx1bWJpbmcgYXMgYSBodW1ibGUgYWN0aXZpdHkgYW5kIHRvbGVyYXRlcyBzaG9kZGluZXNzIGluIHBoaWxvc29waHkgYmVjYXVzZSBpdCBpcyBhbiBleGFsdGVkIGFjdGl2aXR5IHdpbGwgaGF2ZSBuZWl0aGVyIGdvb2QgcGx1bWJpbmcgbm9yIGdvb2QgcGhpbG9zb3BoeTogbmVpdGhlciBpdHMgcGlwZXMgbm9yIGl0cyB0aGVvcmllcyB3aWxsIGhvbGQgd2F0ZXIuCg=="
        }
    ]
}

Success 200

Field Type Description
id Number

The ID of the comment

user_id Number

The ID of the user who posted the comment

text String

The content of the comment

created_at DateTime

The date and time the comment was created in UTC

files Array

An array of files attached to the reply

deleted_by String

The username of the user who deleted the ticket, if it has been deleted. null otherwise.

deleted_at DateTime

A UTC timestamp when the ticket was deleted, if it has been deleted. null otherwise.

HTTP/1.1 201 OK
{
  "data": {
    "id": 4,
    "user_id": 1,
    "text": "Well, here's a story all about how my ticket got flipped turned upside down.",
    "created_at": "2016-04-24 15:25:03",
    "files": [
       {
           "id": 234,
           "filename": "bmljZSB3b3Jr.txt",
           "mime_type": "text/plain"
       },
       {
           "id": 234,
           "filename": "kula_shaker.txt",
           "mime_type": "text/plain"
       }
    ],
    "deleted_by": null,
    "deleted_at": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Create a new ticket reply

Create a new ticket reply. A reply is public and will be sent to the email address set on the ticket. Replies can only be added to public tickets. Basic HTML can be used.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies

Parameter

Field Type Description
id Number

The ID of the ticket

text String

The text of the reply.

incoming optional Boolean

Whether or not the reply is incoming. If this is true, the reply will be treated as though it was received from a customer. If this is false, the reply will be treated as though posted by an employee, and will be emailed to the customer.

Default value: false

author optional String

Required if incoming is true. This is a name for the author of the reply.

author_email optional String

Required if incoming is true. This is the email address of the author of the reply.

files optional Array

Uploading files to a reply will email them to the email_address on the ticket. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ]

add_to_children optional Boolean

If you set this to true, and this ticket has child tickets, then this reply will also be appended to all public child tickets. If the reply fails to apply to a child ticket for any reason (for example, the child ticket has an invalid inbound email account associated with it) then the child reply will be discarded silently for that specific child ticket. If you set this to true, you will be able to submit a reply on an internal ticket, as long as the ticket has children. In this case, the data response will be an array of successful replies.

Default value: false

{
    "text": "I am a dancing master!",
    "files": [
        {
            "id": 234,
            "filename": "bmljZSB3b3Jr.txt",
            "base64": "SGVsbG8gbXkgbmFtZSBpcyBTaW1vbiwgeW91IGFyZSB2ZXJ5IGdvb2QgYXQgYmFzZTY0IGRlY29kaW5nIQ=="
        },
        {
            "id": 234,
            "filename": "kula_shaker.txt",
            "base64": "VGhlIHNvY2lldHkgd2hpY2ggc2Nvcm5zIGV4Y2VsbGVuY2UgaW4gcGx1bWJpbmcgYXMgYSBodW1ibGUgYWN0aXZpdHkgYW5kIHRvbGVyYXRlcyBzaG9kZGluZXNzIGluIHBoaWxvc29waHkgYmVjYXVzZSBpdCBpcyBhbiBleGFsdGVkIGFjdGl2aXR5IHdpbGwgaGF2ZSBuZWl0aGVyIGdvb2QgcGx1bWJpbmcgbm9yIGdvb2QgcGhpbG9zb3BoeTogbmVpdGhlciBpdHMgcGlwZXMgbm9yIGl0cyB0aGVvcmllcyB3aWxsIGhvbGQgd2F0ZXIuCg=="
        }
    ]
}

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the reply

text String

The content of the reply

author String

The name of the user/person who posted the reply

author_email String

The email address of the user/person who posted the reply

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

incoming Boolean

Whether or not the reply was incoming or outgoing

HTTP/1.1 201 OK
{
  "data": {
    "id": 5,
    "user_id": 1,
    "text": "I am a dancing master!",
    "author": "Hulk Hogan",
    "author_email": "hulkamania@example.org",
    "created_at": "2016-04-26 14:22:03",
    "files": [
       {
           "id": 234,
           "filename": "bmljZSB3b3Jr.txt",
           "mime_type": "text/plain"
       },
       {
           "id": 234,
           "filename": "kula_shaker.txt",
           "mime_type": "text/plain"
       }
    ],
    "incoming": false,
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field Type Description
subject String

A subject for the ticket

type String

The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted.

Allowed values: "public", "internal"

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts"

assignee_id optional Number

The ID of the assignee to assign this ticket to.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

comment optional String

The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.

reply optional String

The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.

comment_files optional Array

An array of files to attach to the comment. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ].

reply_files optional Array

Uploading files to a reply will email them to the email_address on the ticket. The format of the files array is [ { "filename": "a_beautiful_picture.png", "base64": "base64_encoded_file_string" }, { "filename": "another_file.mp3", "base64": "base64_encoded_file_string" } ].

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open. Newly created tickets are always open by default

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.

closed_at Date

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field Type Description
subject String

A subject for the ticket

type String

The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted. You can only create a public ticket on an account.

Allowed values: "public", "internal"

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts", "network_sites"

assignee_id optional Number

The ID of the assignee to assign this ticket to.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

comment optional String

The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.

reply optional String

The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts", "network_sites"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open. Newly created tickets are always open by default

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.

closed_at Date

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Create a new ticket

Create a new ticket.

https://example.sonar.software/api/v1/tickets

Parameter

Field Type Description
subject String

A subject for the ticket

type String

The type of ticket. Internal is for internal use only. Public will send emails to a customer if a reply is posted.

Allowed values: "public", "internal"

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, ignored if the ticket is internal.

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts"

assignee_id optional Number

The ID of the assignee to assign this ticket to.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

comment optional String

The first comment for the ticket. A comment is internal only and will not be sent to a customer. A ticket must have at least one comment or reply to open it.

reply optional String

The first reply for the ticket. A reply is public and will be sent to the email address on the ticket. A reply can only be saved if the ticket has an email address.

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open. Newly created tickets are always open by default

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply. Will always be false if the ticket is internal.

closed_at Date

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Delete a ticket

Delete a ticket. This will remove all tasks, files, and other attached items as well.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ID of the ticket

task_id Number

The ID of the task

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the ticket could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Ticket does not exist.",
         "status_code": 404
     }
 }

Tickets - Delete ticket comment

Delete a ticket comment. You can only delete your own comments, unless you are a ticket super user. This will set deleted_at and deleted_by on the comment, and remove the comment text.

https://example.sonar.software/api/v1/tickets/:ticket_id/ticket_comments/:comment_id

Parameter

Field Type Description
ticket_id Number

The ID of the ticket

comment_id Number

The ID of the comment

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the comment could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Comment does not exist.",
         "status_code": 404
     }
 }

Tickets - Detach a child ticket from a parent ticket

Detach a child ticket from a parent ticket.

https://example.sonar.software/api/v1/tickets/:id/detach/:child_id

Parameter

Field Type Description
id Number

The ID of the parent ticket

child_id Number

The ID of the child ticket

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open. Newly created tickets are always open by default

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": []
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The ticket ID 12 is not a child of ticket ID 43."
     },
     "status_code": 422
   }
 }

Tickets - Get a list of subscribed tickets

Get a list of the ticket IDs you are currently subscribed to.

https://example.sonar.software/api/v1/tickets/subscribed

Success 200

Field Type Description
ticket_ids Array

Array of ticket IDs.

HTTP/1.1 201 OK
{
  "data": {
    "ticket_ids": []
  }
}

Tickets - Get all comments on a ticket

Get a list of comments for a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments

Parameter

Field Type Description
id Number

The ID of the ticket

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the comment.

text String

The content of the comment

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

deleted_by String

The username of the user who deleted the ticket, if it has been deleted. null otherwise.

deleted_at DateTime

A UTC timestamp when the ticket was deleted, if it has been deleted. null otherwise.

 HTTP/1.1 201 OK
 {
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "text": "There is a big problem here, the pedestal is full of snakes!",
      "created_at": "2016-04-21 22:00:55",
      "files": [],
      "deleted_by": null,
      "deleted_at": null
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all replies on a ticket

Get a list of replies for a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies

Parameter

Field Type Description
id Number

The ID of the ticket

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the reply. This will be null if the reply was received from an external source (e.g. inbound email.)

text String

The content of the reply

author String

The name of the user/person who posted the reply

author_email String

The email address of the user/person who posted the reply

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

incoming Boolean

Whether or not the reply was incoming or outgoing

HTTP/1.1 201 OK
{
  "data": [
    {
      "id": 66,
      "user_id": null,
      "text": "Some test reply",
      "author": "Simon Westlake",
      "author_email": "simon@sonar.software",
      "created_at": "2016-05-03 15:15:03",
      "files": [
        {
          "id": 19,
          "filename": "Invoice for March 2016.odt",
          "mime_type": "application/vnd.oasis.opendocument.text"
        },
        {
          "id": 18,
          "filename": "Invoice for July 2015.pdf",
          "mime_type": "application/pdf"
        }
      ]
    },
    "incoming": false
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get all tickets for an entity

Get all tickets for a specific entity (e.g. an account

https://example.sonar.software/api/v1/:entity/:entity_id/tickets

Parameter

Field Type Description
entity String

The entity to get tickets for (e.g. accounts)

entity_id Number

The ID of the entity to get tickets for

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all tickets

Get all tickets

https://example.sonar.software/api/v1/tickets

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts", "network_sites"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    },
    {
      "id": 1,
      "subject": "The porridge was too cold",
      "type": "internal",
      "ticket_group_id": 1,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": '2016-04-02',
      "email_address": 'goldilocks@sonar.software',
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": false,
       "parent_ticket_id": null,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get all tickets

Get all tickets

https://example.sonar.software/api/v1/tickets

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "subject": "The porridge was too hot",
      "type": "internal",
      "ticket_group_id": null,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": null,
      "email_address": null,
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": true,
       "parent_ticket_id": 1,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    },
    {
      "id": 1,
      "subject": "The porridge was too cold",
      "type": "internal",
      "ticket_group_id": 1,
      "user_id": 1,
      "assignee": "accounts",
      "assignee_id": 1,
      "due_date": '2016-04-02',
      "email_address": 'goldilocks@sonar.software',
      "priority": 3,
       "category_ids": [
           1,
           2,
           3
       ],
       "open": false,
       "parent_ticket_id": null,
       "child_ticket_ids": [],
       "inbound_email_account_id": null,
       "spam": false,
       "last_reply_incoming": false,
        "closed_at": null,
        "closed_by_user_id": null,
        "created_at": "2016-05-20 14:19:35"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Tickets - Get an individual ticket reply

Get a specific reply on a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_replies/:reply_id

Parameter

Field Type Description
id Number

The ID of the ticket

reply_id Number

The ID of the reply

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the reply. This will be null if the reply was received from an external source (e.g. inbound email.)

text String

The content of the reply

author String

The name of the user/person who posted the reply

author_email String

The email address of the user/person who posted the reply

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

incoming Boolean

Whether or not the reply was incoming or outgoing

HTTP/1.1 201 OK
{
  "data": {
    "id": 66,
    "user_id": null,
    "author": "Simon Westlake",
    "author_email": "simon@sonar.software",
    "text": "Writing ticket replies is so easy, a caveman could do it!",
    "created_at": "2016-05-03 15:15:03",
    "files": [
      {
        "id": 19,
        "filename": "Invoice for March 2016.odt",
        "mime_type": "application/vnd.oasis.opendocument.text"
      },
      {
        "id": 18,
        "filename": "Invoice for July 2015.pdf",
        "mime_type": "application/pdf"
      }
    ]
  },
  "incoming": false
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get individual ticket comment

Get a a specific comment on a ticket.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments/:comment_id

Parameter

Field Type Description
id Number

The ID of the ticket

comment_id Number

The ID of the comment

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the comment.

text String

The content of the comment

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

deleted_by String

The username of the user who deleted the ticket, if it has been deleted. null otherwise.

deleted_at DateTime

A UTC timestamp when the ticket was deleted, if it has been deleted. null otherwise.

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "user_id": 1,
    "text": "I just wanted to say how nice this ticket is.",
    "created_at": "2016-04-21 22:00:55",
    "files": [],
    "deleted_by": null,
    "deleted_at": null
  }
}

Tickets - Get individual ticket

Get an individual ticket

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ID of the ticket

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts", "network_sites"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       5,
       7
    ],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Get individual ticket

Get an individual ticket

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ID of the ticket

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

child_ticket_ids Array

An array of child ticket IDs of this ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": null,
    "child_ticket_ids": [
       5,
       7
    ],
    "inbound_email_account_id": null,
    "spam": false,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Merge two tickets

Merge one ticket into another. The ticket referenced as :id will be kept, and the ticket merging into :id will be deleted. When merging one ticket into another, the ticket referenced as :id will gain all the replies and comments on the ticket referenced in child_ticket_id, and the child_ticket_id ticket will be deleted.

https://example.sonar.software/api/v1/tickets/:id/merge

Parameter

Field Type Description
id Number

The ID of the master ticket

child_ticket_id Number

The ID of the ticket to merge in.

success Boolean

Will be true if the merge succeeds.

HTTP/1.1 200 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "You cannot merge a ticket into itself.",
     "status_code": 422
   }
 }

Tickets - Subscribe to a ticket

Subscribe to a ticket. This will add it to your list of subscribed tickets.

https://example.sonar.software/api/v1/tickets/:id/subscribe

Parameter

Field Type Description
id Number

The ID of the ticket

Success 200

Field Type Description
success Boolean

Will be true if subscription succeeded

HTTP/1.1 201 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Unsubscribe from a ticket

Unsubscribe from a ticket. This will remove it from your list of subscribed tickets.

https://example.sonar.software/api/v1/tickets/:id/unsubscribe

Parameter

Field Type Description
id Number

The ID of the ticket

Success 200

Field Type Description
success Boolean

Will be true if unsubscription succeeded

HTTP/1.1 201 OK
{
  "data": {
    "success": true
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Tickets - Update ticket comment

Update an existing ticket comment. You can only update your own comments, unless you are a ticket super user.

https://example.sonar.software/api/v1/tickets/:id/ticket_comments/:comment_id

Parameter

Field Type Description
id Number

The ticket ID

comment_id Number

The comment ID

text String

The text of the comment

Success 200

Field Type Description
id Number

The ID of the reply

user_id Number

The ID of the user who posted the comment.

text String

The content of the comment

created_at DateTime

The date and time the reply was created in UTC

files Array

An array of files attached to the reply

deleted_by String

The username of the user who deleted the ticket, if it has been deleted. null otherwise.

deleted_at DateTime

A UTC timestamp when the ticket was deleted, if it has been deleted. null otherwise.

HTTP/1.1 201 OK
{
  "data": {
    "id": 8,
    "user_id": 1,
    "text": "This is my updated comment.",
    "created_at": "2016-05-26 17:41:08",
    "files": [],
    "deleted_by": null,
    "deleted_at": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "text": "The text field is required."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ticket ID

subject optional String

A subject for the ticket

type optional String

If this is provided, and it differs from the existing type, it will move the ticket to this type. If you are switching a ticket from internal to public, you must also supply the inbound_email_account_id and email_address properties.

Allowed values: "internal", "public"

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts", "network_sites"

assignee_id optional Number

The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

open optional Boolean

Whether the ticket is open or closed. Send false to close the ticket, true to open it.

child_ticket_ids optional Array

An array of child ticket IDs of this ticket

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.

spam optional Boolean

Whether or not the ticket is spam

update_child_status optional Boolean

If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to true.

Default value: false

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts", "network_sites"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ticket ID

subject optional String

A subject for the ticket

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts", "network_sites"

assignee_id optional Number

The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

open optional Boolean

Whether the ticket is open or closed. Send false to close the ticket, true to open it.

child_ticket_ids optional Array

An array of child ticket IDs of this ticket

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.

spam optional Boolean

Whether or not the ticket is spam

update_child_status optional Boolean

If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to true.

Default value: false

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts", "network_sites"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Tickets - Update ticket

Update an existing ticket.

https://example.sonar.software/api/v1/tickets/:id

Parameter

Field Type Description
id Number

The ticket ID

subject optional String

A subject for the ticket

ticket_group_id optional Number

A valid ID for a ticket group. A ticket must have at least a group or a responsible user.

category_ids optional Array

An array of ticket category IDs to assign to this ticket.

user_id optional Number

A valid responsible user ID. A ticket must have at least a group or a responsible user.

assignee optional String

The type of entity to assign the ticket to. Public tickets can only be assigned to accounts.

Allowed values: "accounts"

assignee_id optional Number

The ID of the assignee to assign this ticket to. If this is set, assignee must be set and vice versa.

due_date optional Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address optional String

An email address, required if this is a public ticket.

priority optional Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Default value: 4

Allowed values: 1, 2, 3, 4

open optional Boolean

Whether the ticket is open or closed. Send false to close the ticket, true to open it.

child_ticket_ids optional Array

An array of child ticket IDs of this ticket

inbound_email_account_id optional Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Can only be set on a public ticket.

spam optional Boolean

Whether or not the ticket is spam

update_child_status optional Boolean

If this ticket has child tickets, and you wish to update them all with whatever the status is of this ticket, set this to true. For example, if this ticket is closed, or you are closing it, and you want to update all child tickets to closed, set this value to true.

Default value: false

Success 200

Field Type Description
id Number

The ID of the ticket.

subject String

A subject for the ticket.

type String

The type of ticket.

ticket_group_id Number

The ticket group for the ticket.

user_id Number

The responsible user for the ticket.

assignee String

The type of entity the ticket is assigned to.

Allowed values: "accounts"

assignee_id Number

The ID of the assignee that the ticket is assigned to.

due_date Date

A date in Y-m-d format that dictates when the ticket must be completed by.

email_address String

An email address, if this is a ticket that will accept replies. Replies are used to communicate with an external party (typically a customer.)

priority Number

A priority for the ticket. 4 is low, 3 is medium, 2 is high, 1 is critical.

Allowed values: 1, 2, 3, 4

category_ids Array

An array of category IDs for this ticket

open Boolean

Whether or not the ticket is open

parent_ticket_id Number

If this ticket is a child ticket, this will be the ID of the parent ticket

inbound_email_account_id Number

The inbound email account to use for this public ticket. This will control the 'From' address that email replies to customers are sent from. Required if the ticket is public, will always be null for internal.

spam Boolean

Whether or not the ticket is spam flagged

last_reply_incoming Boolean

Whether or not the last reply posted to a ticket was an incoming reply

closed_at DateTime

If the ticket is closed, this is the date and time it was closed in UTC

closed_by_user_id Number

If the ticket is closed, this is the user ID of the user that closed it

created_at DateTime

The date and time a ticket was created, in UTC

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "subject": "The porridge was too hot",
    "type": "internal",
    "ticket_group_id": null,
    "user_id": 1,
    "assignee": "accounts",
    "assignee_id": 1,
    "due_date": null,
    "email_address": null,
    "priority": 3,
    "category_ids": [
       1,
       2,
       3
    ],
    "open": true,
    "parent_ticket_id": 3,
    "child_ticket_ids": [],
    "inbound_email_account_id": null,
    "spam": true,
    "last_reply_incoming": false,
    "closed_at": null,
    "closed_by_user_id": null,
    "created_at": "2016-05-20 14:19:35"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "user_id": "The selected user is invalid."
     },
     "status_code": 422
   }
 }

Transaction Batches

Transaction_Batches - Create a new transaction batch

Create a new transaction batch. A transaction batch allows you to import multiple transactions in a single call. The transactions will be queued and entered in the background, and any failures will be sent to you as a notification.

https://example.sonar.software/api/v1/financial/transaction_batches

Parameter

Field Type Description
name optional String

A name for the transaction batch

batch_id optional String

A batch ID. This is not required, but recommended. If you submit a batch ID, then any further imports submitted with the same batch ID will be rejected. This is a safeguard to ensure external systems aren't submitting the same batches multiple times.

transactions Array

An array of objects, the objects representing transactions to import. See the example below for a visual representation of the structure. The values below this line show the content of each object within this array.

account_id Integer

An account ID to add a transaction to

service_id Integer

The service ID to use when adding the transaction

quantity optional Integer

The quantity to use when running the transaction. This is only valid for recurring and one time services.

Default value: 1

description_override optional String

If you want the transaction description to be overridden on the invoice, then enter an override string here

amount Number

An amount to use when adding the transaction. This can only be used when adding adjustment services, and is required if you are adding one. It should be ommitted for other types of services.

override_taxation optional Boolean

If this is true, then any taxes associated with the service referenced by service_id will not be applied. Instead, the tax amounts specified in the tax_transactions property will be used. If tax_transactions is missing or empty, instead, no tax will be applied.

Default value: false

tax_transactions optional Array

An array of objects, only used if override_taxation is true. Each object should have two properties, description and amount. These amounts will be applied to the service as taxes, with the tax name being the description property.

{
     "name": "My first batch",
     "batch_id": "acme-12345",
     "transactions": [
         {
             "account_id": 3,
             "service_id": 89,
             "quantity": 12,
             "override_taxation": false
         },
         {
             "account_id": 3,
             "service_id": 55,
             "description_override": "After Hours Support",
             "override_taxation": true //Here, no taxes will be applied even if service_id 55 has taxes, because we are overriding taxes and supplying no transactions
         },
         {
             "account_id": 55,
             "service_id": 53,
             "amount": 12.53,
             "description_override": "Custom painting charge",
             "override_taxation": true,
             "tax_transactions": [
                 {
                     "amount": 12.43,
                     "description": "Some tax"
                 }
             ]
         }
     ]
}

Success 200

Field Type Description
id Integer

The ID of the transaction batch.

batch_id String

The batch ID. If you did not supply one, a random one is generated.

name String

The name of the transaction batch

created_at DateTime

The date and time the batch was created, in UTC.

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "batch_id": "acme-12345",
    "name": "My first batch",
    "created_at": "2016-11-15 20:16:39"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "batch_id": "The batch id must be unique."
     },
     "status_code": 422
   }
 }

Transaction_Batches - Create a new transaction batch

Create a new transaction batch. A transaction batch allows you to import multiple transactions in a single call. The transactions will be queued and entered in the background, and any failures will be sent to you as a notification.

https://example.sonar.software/api/v1/financial/transaction_batches

Parameter

Field Type Description
name optional String

A name for the transaction batch

batch_id optional String

A batch ID. This is not required, but recommended. If you submit a batch ID, then any further imports submitted with the same batch ID will be rejected. This is a safeguard to ensure external systems aren't submitting the same batches multiple times.

transactions Array

An array of objects, the objects representing transactions to import. See the example below for a visual representation of the structure. The values below this line show the content of each object within this array.

account_id Integer

An account ID to add a transaction to

service_id Integer

The service ID to use when adding the transaction

quantity optional Integer

The quantity to use when running the transaction. This is only valid for recurring and one time services.

Default value: 1

description_override optional String

If you want the transaction description to be overridden on the invoice, then enter an override string here

amount Number

An amount to use when adding the transaction. This can only be used when adding adjustment services, and is required if you are adding one. It should be ommitted for other types of services.

{
    "name": "My first batch",
    "batch_id": "acme-12345",
    "transactions": [
        {
            "account_id": 3,
            "service_id": 89,
            "quantity": 12
        },
        {
            "account_id": 3,
            "service_id": 55,
            "description_override": "After Hours Support"
        },
        {
            "account_id": 55,
            "service_id": 53,
            "amount": 12.53,
            "description_override": "Custom painting charge"
        }
    ]
}

Success 200

Field Type Description
id Integer

The ID of the transaction batch.

batch_id String

The batch ID. If you did not supply one, a random one is generated.

name String

The name of the transaction batch

created_at DateTime

The date and time the batch was created, in UTC.

HTTP/1.1 201 OK
{
  "data": {
    "id": 3,
    "batch_id": "acme-12345",
    "name": "My first batch",
    "created_at": "2016-11-15 20:16:39"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "batch_id": "The batch id must be unique."
     },
     "status_code": 422
   }
 }

Usage Based Billing Policies

Usage_Based_Billing_Policies - Create a new usage based billing free period

Create a new usage based billing free period.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods

Parameter

Field Type Description
usage_based_billing_policy_id Number

The ID of the usage based billing policy.

day Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start Time

The start of the free period in HH:MM:SS

end Time

The end of the free period in HH:MM:SS

Success 200

Field Type Description
id Number

The ID of the usage based billing free period.

day Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start Time

The start of the free period in HH:MM:SS

end Time

The end of the free period in HH:MM:SS

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": "This free period overlaps another defined free period from 09:00:00 to 21:32:00.",
     "status_code": 422
   }
 }

Usage_Based_Billing_Policies - Create a new usage based billing policy

Create a new usage based billing policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies

Parameter

Field Type Description
description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months optional Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months. This is required if rollover_expiration_enabled is true!

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id optional Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions. This is required if either of the aforementioned properties are true!

Success 200

Field Type Description
id Number

The ID of the usage based billing policy.

description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions.

HTTP/1.1 201 OK
{
  "data": {
    "id": 9,
    "description": "Test 123",
    "cap_in_gigabytes": 150,
    "rollover_enabled": false,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "service_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "description": "The description must be unique."
     },
     "status_code": 422
   }
 }

Usage_Based_Billing_Policies - Delete a usage based billing free period

Delete a usage based billing free period

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field Type Description
usage_based_billing_policy_id Number

The ID of the usage based billing policy

id Number

The ID of the usage based billing free period

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the usage based billing free period could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Usage based billing free period does not exist.",
         "status_code": 404
     }
 }

Usage_Based_Billing_Policies - Delete a usage based billing policy

Delete a usage based billing policy. If this is currently on any services, it will be removed from the services, and all users with those services will no longer have a usage cap.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field Type Description
id Number

The ID of the usage based billing policy

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the usage based billing policy could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Usage based billing policy does not exist.",
         "status_code": 404
     }
 }

Usage_Based_Billing_Policies - Get all usage based billing free periods

Get all usage based billing free periods for a specific policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods

Parameter

Field Type Description
usage_based_billing_policy_id Number

The ID of the usage based billing policy the free period is attached to

limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the usage based billing free period.

day Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start Time

The start of the free period in HH:MM:SS

end Time

The end of the free period in HH:MM:SS

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "day": 0,
      "start": "00:00:00",
      "end": "02:30:00"
    }
  ],
  "paginator": {
    "total_count": 1,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Usage_Based_Billing_Policies - Get all usage based billing policies

Get all usage based billing policies

https://example.sonar.software/api/v1/system/usage_based_billing_policies

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the usage based billing policy.

description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions.

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 1,
      "description": "No Rollover",
      "cap_in_gigabytes": 5,
      "rollover_enabled": false,
      "rollover_expiration_enabled": false,
      "rollover_expires_after_months": 0,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": false,
      "service_id": null
    },
    {
      "id": 3,
      "description": "Rollover No Expiration",
      "cap_in_gigabytes": 1,
      "rollover_enabled": true,
      "rollover_expiration_enabled": false,
      "rollover_expires_after_months": 0,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": false,
      "service_id": null
    },
    {
      "id": 2,
      "description": "Rollover 3 month expiration",
      "cap_in_gigabytes": 1,
      "rollover_enabled": true,
      "rollover_expiration_enabled": true,
      "rollover_expires_after_months": 3,
      "assess_charges_at_end_of_billing_period": false,
      "allow_user_to_purchase_capacity": true,
      "service_id": 15
    }
  ],
  "paginator": {
    "total_count": 3,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Usage_Based_Billing_Policies - Get an individual usage based billing free period

Get an individual usage based billing free period

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field Type Description
usage_based_billing_policy_id Number

The ID of the usage based billing policy the free period is attached to

id Number

The ID of the usage based billing free period

Success 200

Field Type Description
id Number

The ID of the usage based billing free period.

day Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start Time

The start of the free period in HH:MM:SS

end Time

The end of the free period in HH:MM:SS

HTTP/1.1 200 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Usage_Based_Billing_Policies - Get an individual usage based billing policy

Get an individual usage based billing policy

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field Type Description
id Number

The ID of the usage based billing policy

Success 200

Field Type Description
id Number

The ID of the usage based billing policy.

description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "description": "Rollover 3 month expiration",
    "cap_in_gigabytes": 1,
    "rollover_enabled": true,
    "rollover_expiration_enabled": true,
    "rollover_expires_after_months": 3,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": true,
    "service_id": 15
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Usage_Based_Billing_Policies - Update usage based billing free period

Update an existing usage based billing free period.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:usage_based_billing_policy_id/usage_based_billing_free_periods/:id

Parameter

Field Type Description
usage_based_billing_policy_id Number

The ID of the usage based billing policy.

id Number

The ID of the usage based billing free period

day optional Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start optional Time

The start of the free period in HH:MM:SS

end optional Time

The end of the free period in HH:MM:SS

Success 200

Field Type Description
id Number

The ID of the usage based billing free period.

day Number

The day of the week of the free period, where 0 is Sunday and 6 is Saturday

start Time

The start of the free period in HH:MM:SS

end Time

The end of the free period in HH:MM:SS

HTTP/1.1 201 OK
{
  "data": {
    "id": 1,
    "day": 0,
    "start": "00:00:00",
    "end": "02:30:00"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Usage_Based_Billing_Policies - Update usage based billing policy

Update an existing usage based billing policy.

https://example.sonar.software/api/v1/system/usage_based_billing_policies/:id

Parameter

Field Type Description
id Number

The usage based billing policy ID

description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months optional Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months. This is required if rollover_expiration_enabled is true!

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id optional Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions. This is required if either of the aforementioned properties are true!

Success 200

Field Type Description
id Number

The ID of the usage based billing policy.

description String

A description of the policy.

cap_in_gigabytes Number

The cap on the policy, in gigabytes.

rollover_enabled Boolean

If rollover is enabled on this policy.

rollover_expiration_enabled Boolean

If rollover data expires

rollover_expires_after_months Number

If rollover_expiration_enabled is true, then any unused data rolled over expires after this many months

assess_charges_at_end_of_billing_period Boolean

If this is true, then any data usage over cap_in_gigabytes will be charged at the rates defined in the overage service linked as service_id

allow_user_to_purchase_capacity Boolean

If this is true, then a user can purchase additional data mid-billing period (referred to as a 'top off' inside Sonar) at the rates defined in the overage service linked as service_id

service_id Number

If either assess_charges_at_end_of_billing_period or allow_user_to_purchase_capacity are true, then this is the ID of the overage service used to determine the rates for those functions.

HTTP/1.1 200 OK
{
  "data": {
    "id": 9,
    "description": "Test 123",
    "cap_in_gigabytes": 150,
    "rollover_enabled": false,
    "rollover_expiration_enabled": false,
    "rollover_expires_after_months": 0,
    "assess_charges_at_end_of_billing_period": false,
    "allow_user_to_purchase_capacity": false,
    "service_id": null
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Users

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field Type Description
username String

A unique username for the user

password String

A plain text password

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address String

The email address for the user

mobile_number optional Number

The mobile telephone number for the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

mobile_number Number

The mobile telephone number for the user

HTTP/1.1 201 OK
{
    "data": {
        "id": 15,
        "username": "Hansolo",
        "name": "Han Solo",
        "public_name": "Han S.",
        "locale": "en",
        "role_id": 3,
        "email_address": "test@example.com",
        "mobile_number": null
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field Type Description
username String

A unique username for the user

password String

A plain text password

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address String

The email address for the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "John_Doe@example.com"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field Type Description
username String

A unique username for the user

password String

A plain text password

name String

The name of the user

role_id Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address String

The email address for the user

locale optional String

A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

Default value: System Default

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

locale String

A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "role_id": 1,
        "email_address": "John_Doe@example.com",
        "locale": "en"
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Create user

Create a new user.

https://example.sonar.software/api/v1/users

Parameter

Field Type Description
username String

A unique username for the user

password String

A plain text password

name String

The name of the user

role_id Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address String

The email address for the user

api Boolean

Whether or not the user has API access

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

api Boolean

Whether or not the user has API access

HTTP/1.1 201 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "John Doe",
        "role_id": 1,
        "email_address": "John_Doe@example.com",
        "api": true
   }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Delete user

Delete a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field Type Description
id Number

The ID of the user

Success 200

Field Type Description
message String

A message stating that the deletion was successful.

HTTP/1.1 200 OK
{
    "data": {
        "message": "User deleted"
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the user could not be deleted

status_code Number

4xx

HTTP/1.1 422
 {
     "error": {
         "message": "You cannot delete the last user with super admin privileges.",
         "status_code": 422
     }
 }

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

locale String

The users preferred locale

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

mobile_number Number

The mobile telephone number for the user

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "mobile_number": "4148675309"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "public_name": "Johnny D",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "mobile_number": null
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

locale String

The users preferred locale

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "public_name": "Johnny D",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software"
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

locale String

The users preferred locale

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "role_id": 3,
            "email_address": "test@example.com",
            "locale": "en"
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "locale": "en"
        }
    ]
}

Users - Get all users

Get a list of users from within Sonar.

https://example.sonar.software/api/v1/users/

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

locale String

The users preferred locale

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

api Boolean

Whether or not the user has API access

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "api": true
        },
        {
            "id": 11,
            "username": "admin",
            "name": "John Doe the Third",
            "locale": "en",
            "role_id": 1,
            "email_address": "simon@sonar.software",
            "api": true
        }
    ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id
curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field Type Description
id Number

The id of the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

mobile_number Number

The mobile telephone number for the user

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "mobile_number": null
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id
curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field Type Description
id Number

The id of the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "public_name": "Han S.",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com"
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id
curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field Type Description
id Number

The id of the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

locale String

A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "role_id": 3,
            "email_address": "test@example.com",
            "locale": "en"
        }
   ]
}

Users - Get individual user

Get data on an Get individual user.

https://example.sonar.software/api/v1/users/:id
curl -i https://example.sonar.software/api/v1/users/15

Parameter

Field Type Description
id Number

The id of the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

api Boolean

Whether or not the user has API access

HTTP/1.1 200 OK
{
    "data": [
        {
            "id": 15,
            "username": "Hansolo",
            "name": "Han Solo",
            "locale": "en",
            "role_id": 3,
            "email_address": "test@example.com",
            "api": true
        }
   ]
}

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field Type Description
id Number

The ID of the user

username optional String

The username of the user

password optional String

A plain text password for the user

name optional String

The name of the user

public_name optional String

The public name of the user

role_id optional Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address optional String

The email address for the user

mobile_number optional Number

The mobile telephone number for the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

mobile_number Number

The mobile telephone number for the user

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "Jonathan Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "mobile_number": null
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field Type Description
id Number

The ID of the user

username optional String

The username of the user

password optional String

A plain text password for the user

name optional String

The name of the user

public_name optional String

The public name of the user

role_id optional Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address optional String

The email address for the user

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

public_name String

The public name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "name": "Jonathan Doe",
        "public_name": "John D",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com"
    }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field Type Description
id Number

The ID of the user

username optional String

The username of the user

password optional String

A plain text password for the user

name optional String

The name of the user

role_id optional Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address optional String

The email address for the user

locale optional String

A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

must_reset optional Boolean

Set this to true to force the user to reset their password on next login.

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

locale String

A valid locale (language) for the user. You can get a list of valid locales from /_data/locales.

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "first_name": "Jonathan Doe",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "locale": "en"
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Users - Update user

Update a user

https://example.sonar.software/api/v1/users/:id

Parameter

Field Type Description
id Number

The ID of the user

username optional String

The username of the user

password optional String

A plain text password for the user

name optional String

The name of the user

role_id optional Number

The ID of the role for this user. These can be loaded from the roles endpoint.

email_address optional String

The email address for the user

api Boolean

Whether or not the user has API access

Success 200

Field Type Description
id Number

The internal id of the user

username String

The username of the user

name String

The name of the user

role_id Number

The ID associated with the role that the user has

email_address String

The email address associated with the user

api Boolean

Whether or not the user has API access

HTTP/1.1 200 OK
{
    "data": {
        "id": 35,
        "username": "JohnDoe",
        "first_name": "Jonathan Doe",
        "role_id": 1,
        "email_address": "Johnathan_Doe@example.com",
        "api": true
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
     "error": {
         "message": {
             "username": "The username has already been taken.",
             "email_address": "The email address has already been taken."
         },
         "status_code": 422
     }
 }

Voice Providers

Voice_Providers - Create a new voice provider

Create a new voice provider.

https://example.sonar.software/api/v1/system/voice/voice_providers

Parameter

Field Type Description
name String

A name for the voice provider

Success 200

Field Type Description
id Number

The ID of the voice provider.

name String

The name of the voice provider

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Flowroute",
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

422

HTTP/1.1 422
 {
   "error": {
     "message": {
       "name": "The name must be unique."
     },
     "status_code": 422
   }
 }

Voice_Providers - Delete a voice provider

Delete a voice provider

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field Type Description
id Number

The ID of the voice provider

Success 200

Field Type Description
success Boolean

Will be true if deletion succeeded.

HTTP/1.1 200 OK
{
    "data": {
        "success": true
    }
}

Error 4xx

Name Type Description
message String

A reason as to why the voice provider could not be deleted

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Voice provider does not exist.",
         "status_code": 404
     }
 }

Voice_Providers - Get all voice providers

Get all voice providers

https://example.sonar.software/api/v1/system/voice/voice_providers

Parameter

Field Type Description
limit optional Number

The number of entries to return

page optional Number

The page of results to return

Success 200

Field Type Description
id Number

The ID of the voice provider.

name String

The name of the voice provider

HTTP/1.1 200 OK
{
  "data": [
    {
      "id": 2,
      "name": "Flowroute"
    },
    {
      "id": 1,
      "name": "Vitelity"
    }
  ],
  "paginator": {
    "total_count": 2,
    "total_pages": 1,
    "current_page": 1,
    "limit": 100
  }
}

Voice_Providers - Get an individual voice provider

Get an individual voice provider

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field Type Description
id Number

The ID of the voice provider

Success 200

Field Type Description
id Number

The ID of the voice provider.

name String

The name of the voice provider.

HTTP/1.1 200 OK
{
  "data": {
    "id": 2,
    "name": "Flowroute"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

404

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }

Voice_Providers - Import a rate deck

Import a rate deck for a voice provider. Please note that hitting this endpoint will delete all existing rates for this provider before beginning new import. In case of a failure, your rates may still be removed, so please ensure you successfully complete and verify a rate deck import when using this endpoint! It may also take some time for a large rate deck to be imported - importing 100,000 rates here can take upwards of 60 seconds. Please ensure you have a sufficiently large timeout set in your script/client when performing this import.

https://example.sonar.software/api/v1/system/voice/voice_providers/:id/import_rates
{
      "minimum_rate": 0.01,
      "percentage_increase": 40,
      "rates": [
             {
                    "name": "ANDORRA",
                    "prefix": "3763",
                    "rate": 0.30786
             },
             {
                    "name": "ANDORRA - MOBILE",
                    "prefix": "3764",
                    "rate": 0.307485
             }
      ]
}

Parameter

Field Type Description
id Number

The ID of the voice provider

rates Array

An array of names, prefixes, and rates. The array should contain multiple objects with a name property that explains the rate, a prefix property that contains the dialed number prefix, and a rate property that represents the rate to call that prefix, per minute, in cents (or whatever the smallest currency denomination you use is.) The rate can be represented as a fraction (float.) Example shown below.

minimum_rate Number

The minimum rate for calls, per minute. You can use this to override the percentage increase in the case where you want a minimum rate that may be higher than the percentage increase for some rates.

percentage_increase Number

A percentage increase, between 0 and 100. This will be used to increase the rate in the rates array by this percentage. If the percentage increase is less than minimum_rate, then the minimum rate will be used instead.

Success 200

Field Type Description
success Boolean

Will be true if import succeeded.

errors Array

If the import succeeded, but some errors were found in the import, they will be enumerated here.

HTTP/1.1 200 OK
{
  "data": {
    "success": true,
    "errors": [
      "Line 3 was skipped as it had a rate or prefix that was not numeric."
    ]
  }
}

Error 4xx

Name Type Description
message String

A list of errors that occurred during import. If some lines fail, the remainder will still be imported.

status_code Number

4x

HTTP/1.1 404
 {
     "error": {
         "message": "Voice provider does not exist.",
         "status_code": 404
     }
 }

Voice_Providers - Update voice provider

Update an existing voice provider.

https://example.sonar.software/api/v1/system/voice/voice_providers/:id

Parameter

Field Type Description
id Number

The voice provider ID

name optional String

The name of the voice provider

Success 200

Field Type Description
id Number

The ID of the voice provider.

name String

The name of the voice provider.

HTTP/1.1 201 OK
{
  "data": {
    "id": 2,
    "name": "Fowroute"
  }
}

Error 4xx

Name Type Description
message String

A list of validation errors

status_code Number

4xx

HTTP/1.1 404
 {
   "error": {
     "message": "No item with that ID found.",
     "status_code": 404
   }
 }
Generated with apidoc 0.16.1 - 2021-09-16T18:14:42.498Z